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.
| 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 |
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-12bd4f3a7c90Do 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.
Last updated on