# Idempotency

Use the Idempotency-Key header to safely retry mutating requests without duplicating work.

URL: https://docs.shiwake.app/docs/api/idempotency



Network failures, timeouts, and retries are facts of life. Shiwake requires
every mutating `/ledger/*` request to carry an `Idempotency-Key` header so the
same request can be retried safely: a replayed request returns the original
result instead of creating duplicate journal entries, holds, or account
mutations.

Which requests require a key? [#which-requests-require-a-key]

Every `POST`, `PUT`, or `PATCH` under `/api/v1/ledger/...` **must** include the
header. Requests without it are rejected with `400 Bad Request` before they
reach a controller.

| Method | Path                                   | Requires `Idempotency-Key` |
| ------ | -------------------------------------- | -------------------------- |
| `POST` | `/ledger/accounts`                     | Yes                        |
| `POST` | `/ledger/accounts/{id}/deactivate`     | Yes                        |
| `POST` | `/ledger/journal-entries`              | Yes                        |
| `POST` | `/ledger/journal-entries/{id}/reverse` | Yes                        |
| `POST` | `/ledger/holds`                        | Yes                        |
| `POST` | `/ledger/holds/{id}/capture`           | Yes                        |
| `POST` | `/ledger/holds/{id}/release`           | Yes                        |
| `GET`  | any `/ledger/*`                        | No                         |
| any    | `/platform/tenants/*`                  | No                         |

<Callout type="info">
  Platform endpoints (`/api/v1/platform/...`) do not enforce idempotency. Tenant management is infrequent and uses a different auth path.
</Callout>

Key format [#key-format]

An idempotency key is any non-empty string up to 255 characters. We recommend
a **UUID v4** generated by the client per logical operation.

```bash
Idempotency-Key: 7a3e2c1d-9f4b-4f7a-8e1a-12bd4f3a7c90
```

Do not reuse a key across different logical operations. If you deposit `50000`
pesewas (GHS 500.00) and then a second unrelated deposit of `25000`, they must
carry different keys.

Replay semantics [#replay-semantics]

When a key is replayed, the engine inspects whether the original request
completed successfully:

* If the original succeeded, the stored response is returned verbatim with the
  same HTTP status and body. No new database writes occur.
* If the original is still in progress (e.g. a concurrent duplicate within the
  same few milliseconds), the replay waits for the original to finish and
  then returns its result.
* If the original failed with a transient error, the replay is treated as a
  fresh attempt.

Keys are scoped **per tenant**. Two tenants may independently use the same
string with no collision.

Missing key [#missing-key]

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="response">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl -X POST https://api.shiwake.example.com/api/v1/ledger/journal-entries \
      -H "X-Api-Key: sk_live_..." \
      -H "Content-Type: application/json" \
      -d '{ "lines": [] }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="response">
    ```json
    {
      "code": 400,
      "message": "Idempotency-Key header is required on all mutating ledger requests.",
      "data": null
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Generating keys in code [#generating-keys-in-code]

<CodeBlockTabs defaultValue="csharp">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="csharp">
      C# (SDK)
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bash">
      bash
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="csharp">
    ```csharp
    var idempotencyKey = Guid.NewGuid().ToString();

    var entry = await ledger.PostJournalEntryAsync(new PostJournalEntryRequest
    {
        Description = "Deposit from acme-finance tenant",
        Lines =
        [
            new("PLATFORM-FLOAT",   "Debit",  50_000),
            new("CLIENT-42",        "Credit", 50_000)
        ]
    }, idempotencyKey);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bash">
    ```bash
    IDEMPOTENCY_KEY=$(uuidgen)

    curl -X POST https://api.shiwake.example.com/api/v1/ledger/journal-entries \
      -H "X-Api-Key: sk_live_..." \
      -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
      -H "Content-Type: application/json" \
      -d '{ ... }'
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Best practices [#best-practices]

* **Persist the key before sending the request.** If the client crashes mid-flight,
  the retry should use the same key so the server can deduplicate.
* **Generate per operation, not per retry.** A retry of the same logical
  operation reuses the original key.
* **Keep keys opaque.** Do not encode business meaning into the key.
* **Do not reuse keys across tenants.** The partition is per-tenant, so the
  same key in two tenants refers to two independent operations.
