ShiwakeDocs

Idempotency

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

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?

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.

MethodPathRequires Idempotency-Key
POST/ledger/accountsYes
POST/ledger/accounts/{id}/deactivateYes
POST/ledger/journal-entriesYes
POST/ledger/journal-entries/{id}/reverseYes
POST/ledger/holdsYes
POST/ledger/holds/{id}/captureYes
POST/ledger/holds/{id}/releaseYes
GETany /ledger/*No
any/platform/tenants/*No

Platform endpoints (/api/v1/platform/...) do not enforce idempotency. Tenant management is infrequent and uses a different auth path.

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.

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

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

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": [] }'

Generating keys in code

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);

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.
Edit on GitHub

Last updated on

On this page