Part 7 · 1 chapters · ~8 min
Idempotency Keys and Retries
Which operations need idempotency keys, the Idempotency-Key header contract, fingerprints and stored responses, retry guidance for clients (which statuses, backoff with jitter, Retry-After), rate limit headers, and documenting retry safety per endpoint.
14
Telling clients how to retry
| response | client should |
|---|---|
| network error or timeout on POST with an idempotency key | retry with the same key |
| 409 request in progress | wait and retry with the same key |
| 429 with Retry-After | wait at least that long |
| 500, 502, 503, 504 | retry with backoff and jitter, limited attempts |
| 400, 401, 403, 404, 422 | do not retry; fix the request |
code
RateLimit-Policy: 100;w=60 RateLimit: limit=100, remaining=12, reset=33 (IETF RateLimit header fields draft) Retry-After: 33
The server side of idempotency (fingerprints, stored responses, in-flight conflicts) is built in full in Ledgers part 2. The API's job is to require the header on every unsafe endpoint, document the retention window, and make the retry rules explicit.