Idempotent API requests
Let API clients retry safely: an Idempotency-Key header, stored answers, and exact rules for two requests that arrive at once.
This is an app part spec on Spekkr, published by vex. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.
- Spec
vex/idempotency-keys- Version
- 0.1.2
- Published by
- vex
- Updated
- 15 Nov 2026
Build this spec
Build the spec at https://spekkr.com/vex/idempotency-keys/start.md.
Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.
Published by vex.
What does the result look like?
What can I customize?
Your choices go into the line you copy. Anything else is yours to edit, but it leaves the tested path.
What do I get?
-
spec.mdRequirements and acceptance criteria.Idempotent API requests
What this builds
A way for the clients of an API to retry a request without doing the work twice. The client sends a key of its own choosing with a request. If the same request comes again with the same key, the API answers what it answered the first time and does nothing more. A dropped connection can then be retried without fear of a second charge, a second order or a second email.
Read
spekkr.inputs.jsonfirst. A key is remembered forkey_hourshours.storesays where keys are kept.require_keydecides whether R8 exists.This spec sits in front of an API's routes. It needs the API to know who is calling, by an API key or a signed-in user.
Out of scope
- Making the handlers themselves safe to run twice. This keeps them from being run twice.
- Retrying on the client's side.
Requirements
Each requirement has an id. Tests name the id they cover.
R1. The header
- A client sends
Idempotency-Keywith aPOSTor aPATCH. The value is 1 to 255 printable ASCII characters. Anything else gets status 400. - On
GET,HEAD,PUTandDELETEthe header is ignored: repeating those is already safe. - A key belongs to the caller who sent it. Two callers who pick the same key never meet.
Accept when: an empty key, a key of 256 characters and a key with a line break each get 400, and the same key from two callers runs the handler twice.
R2. The first request
- Before the handler runs, the key is recorded as in progress, together with the request's fingerprint from
design.md. Recording is one step, so two requests cannot both be first. - The handler runs. Its status, its body and the headers named in
design.mdare stored, and the key is marked done.
Accept when: the fingerprint test vectors in
design.mdare reproduced, and after a first request the store holds the answer.R3. The same request again
- A request with a key that is done and the same fingerprint gets the stored status, headers and body, plus the header
Idempotent-Replayed: true. - The handler does not run.
Accept when: the second answer equals the first byte for byte, and a counter in the handler shows it ran once.
R4. The same key for something else
- A request with a known key and a different fingerprint gets status 422 with the code
idempotency_key_reused. The handler does not run and the stored answer stays.
Accept when: changing one byte of the body under the same key gets 422.
R5. Two at once
- A request whose key is in progress gets status 409 with the code
request_in_progressandRetry-After: 1. It does not wait. - Of 20 requests sent at the same moment with one key, one runs the handler. The others get 409 or, if they arrive after it finished, the stored answer.
Accept when: the test with 20 requests shows the handler ran once and every answer is either the real one, a replay of it, or 409.
R6. What is kept
- An answer with a status from 200 to 499 is stored and replayed. That includes a refusal: retrying a request that was invalid gets the same refusal.
- An answer of 500 or above is not stored. The key is released, so a retry runs the handler again.
- If the process dies while a key is in progress, the key is released 60 seconds after it was recorded.
- If
storeisdatabase, the answer is saved in the same transaction as the handler's own changes. Either both are saved or neither is.
Accept when: a handler that fails with 500 runs again on retry, a key abandoned in progress can be used after 60 seconds, and with
storeset todatabasea handler whose transaction rolls back leaves no stored answer.R7. Forgetting
- A key is forgotten
key_hourshours after it was first used. The same key after that is a new request. - The stored body is at most 1 MB (1,000,000 bytes). A larger answer is sent to the client but not stored, and the key is kept as done with a note; a retry gets status 409 with the code
answer_not_kept.
Accept when: a key works as new one second after it expires, and not one second before.
R8. Keys required
Only if
require_keyis on.- A
POSTwithout the header gets status 400 with the codeidempotency_key_missing. Routes can be marked as exempt.
Accept when: a
POSTwithout a key is refused and an exempt route is not.Definition of done
- Every acceptance check above has an automated test, and all tests pass. Tests set the clock; none of them sleeps.
- A README explains how to put this in front of a route, what a client should send and when to retry, and how to run the tests.
# Idempotent API requests ## What this builds A way for the clients of an API to retry a request without doing the work twice. The client sends a key of its own choosing with a request. If the same request comes again with the same key, the API answers what it answered the first time and does nothing more. A dropped connection can then be retried without fear of a second charge, a second order or a second email. Read `spekkr.inputs.json` first. A key is remembered for `key_hours` hours. `store` says where keys are kept. `require_key` decides whether R8 exists. This spec sits in front of an API's routes. It needs the API to know who is calling, by an API key or a signed-in user. ## Out of scope - Making the handlers themselves safe to run twice. This keeps them from being run twice. - Retrying on the client's side. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. The header - A client sends `Idempotency-Key` with a `POST` or a `PATCH`. The value is 1 to 255 printable ASCII characters. Anything else gets status 400. - On `GET`, `HEAD`, `PUT` and `DELETE` the header is ignored: repeating those is already safe. - A key belongs to the caller who sent it. Two callers who pick the same key never meet. Accept when: an empty key, a key of 256 characters and a key with a line break each get 400, and the same key from two callers runs the handler twice. ### R2. The first request - Before the handler runs, the key is recorded as in progress, together with the request's fingerprint from `design.md`. Recording is one step, so two requests cannot both be first. - The handler runs. Its status, its body and the headers named in `design.md` are stored, and the key is marked done. Accept when: the fingerprint test vectors in `design.md` are reproduced, and after a first request the store holds the answer. ### R3. The same request again - A request with a key that is done and the same fingerprint gets the stored status, headers and body, plus the header `Idempotent-Replayed: true`. - The handler does not run. Accept when: the second answer equals the first byte for byte, and a counter in the handler shows it ran once. ### R4. The same key for something else - A request with a known key and a different fingerprint gets status 422 with the code `idempotency_key_reused`. The handler does not run and the stored answer stays. Accept when: changing one byte of the body under the same key gets 422. ### R5. Two at once - A request whose key is in progress gets status 409 with the code `request_in_progress` and `Retry-After: 1`. It does not wait. - Of 20 requests sent at the same moment with one key, one runs the handler. The others get 409 or, if they arrive after it finished, the stored answer. Accept when: the test with 20 requests shows the handler ran once and every answer is either the real one, a replay of it, or 409. ### R6. What is kept - An answer with a status from 200 to 499 is stored and replayed. That includes a refusal: retrying a request that was invalid gets the same refusal. - An answer of 500 or above is not stored. The key is released, so a retry runs the handler again. - If the process dies while a key is in progress, the key is released 60 seconds after it was recorded. - If `store` is `database`, the answer is saved in the same transaction as the handler's own changes. Either both are saved or neither is. Accept when: a handler that fails with 500 runs again on retry, a key abandoned in progress can be used after 60 seconds, and with `store` set to `database` a handler whose transaction rolls back leaves no stored answer. ### R7. Forgetting - A key is forgotten `key_hours` hours after it was first used. The same key after that is a new request. - The stored body is at most 1 MB (1,000,000 bytes). A larger answer is sent to the client but not stored, and the key is kept as done with a note; a retry gets status 409 with the code `answer_not_kept`. Accept when: a key works as new one second after it expires, and not one second before. ### R8. Keys required Only if `require_key` is on. - A `POST` without the header gets status 400 with the code `idempotency_key_missing`. Routes can be marked as exempt. Accept when: a `POST` without a key is refused and an exempt route is not. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. Tests set the clock; none of them sleeps. - A README explains how to put this in front of a route, what a client should send and when to retry, and how to run the tests.
-
design.mdData model, rules and flows.Design
This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them.
The fingerprint
The fingerprint says whether two requests are the same request.
text = method, a line feed, path with its query string, a line feed, body fingerprint = SHA-256 of text as bytes, in hexadecimalThe body is the raw bytes as they arrived, before any parsing. Two bodies that mean the same but are written differently are different requests.
Method Path Body Fingerprint POST/v1/charges{"amount":1200,"currency":"USD","customer":"cus_42"}4d0c10fdb00e06797b77e271a15858439b230c77bd8aa1ff6150b0fcfc60f7e3POST/v1/charges{"amount":1300,"currency":"USD","customer":"cus_42"}907eed6f8a1eef9697f4da4e0c8a647d4e41071915d4070c9da1cefeee44370dWhat is stored
Field Holds scopeThe caller: an API key's id or a user's id keyThe header's value fingerprintAs above statein_progressordonestatus,headers,bodyThe answer, once done locked_until60 seconds after the key was recorded expires_atkey_hourshours after the key was recordedThe primary key is
scopeandkeytogether. Of the headers, storeContent-TypeandLocationand nothing else: the rest belong to one moment.One request, step by step
- Not a
POSTorPATCH, or no header: pass the request on. - Check the header's value. Work out the scope and the fingerprint.
- Try to record the key as
in_progress. This must be one step that fails if the key is there:
storeThe one step databaseAn INSERTthat does nothing on conflict, then a check of whether a row was writtenredisSETwithNXand an expiry- If it was recorded, run the handler, then store the answer or release the key as R6 says.
- If the key was already there, read it:
What is there Answer Expired Delete it and go back to step 3 Different fingerprint 422 idempotency_key_reuseddoneThe stored answer, with Idempotent-Replayed: truein_progress,locked_untilpassedTake the key over with one conditional update, then step 4 in_progress409 request_in_progressWith
storeset todatabase, run steps 3 and 4 so that marking the keydonecommits together with the handler's changes: the handler uses the same transaction, or a savepoint inside it.Errors
{ "error": { "code": "idempotency_key_reused", "message": "This key was used for a different request." } }Configuration
Secret Purpose DATABASE_URLConnection string, when storeisdatabase.REDIS_URLConnection string, when storeisredis.Named here
- The app says who is calling through one function,
caller(request). A request with no caller gets 401 with the codeunauthenticated. - A key that breaks the rules for a key gets 400 with the code
idempotency_key_invalid. - The method is in capitals in the fingerprint.
- The row that marks a key as in progress is committed on its own, before the handler runs, so that a second request sees it at once. Marking it done commits with the handler's changes.
- The note in R7 is a
notecolumn, and holdsanswer_not_kept.
What this spec leaves to you
Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.
# Design This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them. ## The fingerprint The fingerprint says whether two requests are the same request. ``` text = method, a line feed, path with its query string, a line feed, body fingerprint = SHA-256 of text as bytes, in hexadecimal ``` The body is the raw bytes as they arrived, before any parsing. Two bodies that mean the same but are written differently are different requests. | Method | Path | Body | Fingerprint | | --- | --- | --- | --- | | `POST` | `/v1/charges` | `{"amount":1200,"currency":"USD","customer":"cus_42"}` | `4d0c10fdb00e06797b77e271a15858439b230c77bd8aa1ff6150b0fcfc60f7e3` | | `POST` | `/v1/charges` | `{"amount":1300,"currency":"USD","customer":"cus_42"}` | `907eed6f8a1eef9697f4da4e0c8a647d4e41071915d4070c9da1cefeee44370d` | ## What is stored | Field | Holds | | --- | --- | | `scope` | The caller: an API key's id or a user's id | | `key` | The header's value | | `fingerprint` | As above | | `state` | `in_progress` or `done` | | `status`, `headers`, `body` | The answer, once done | | `locked_until` | 60 seconds after the key was recorded | | `expires_at` | `key_hours` hours after the key was recorded | The primary key is `scope` and `key` together. Of the headers, store `Content-Type` and `Location` and nothing else: the rest belong to one moment. ## One request, step by step 1. Not a `POST` or `PATCH`, or no header: pass the request on. 2. Check the header's value. Work out the scope and the fingerprint. 3. Try to record the key as `in_progress`. This must be one step that fails if the key is there: | `store` | The one step | | --- | --- | | `database` | An `INSERT` that does nothing on conflict, then a check of whether a row was written | | `redis` | `SET` with `NX` and an expiry | 4. If it was recorded, run the handler, then store the answer or release the key as R6 says. 5. If the key was already there, read it: | What is there | Answer | | --- | --- | | Expired | Delete it and go back to step 3 | | Different fingerprint | 422 `idempotency_key_reused` | | `done` | The stored answer, with `Idempotent-Replayed: true` | | `in_progress`, `locked_until` passed | Take the key over with one conditional update, then step 4 | | `in_progress` | 409 `request_in_progress` | With `store` set to `database`, run steps 3 and 4 so that marking the key `done` commits together with the handler's changes: the handler uses the same transaction, or a savepoint inside it. ## Errors ```json { "error": { "code": "idempotency_key_reused", "message": "This key was used for a different request." } } ``` ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string, when `store` is `database`. | | `REDIS_URL` | Connection string, when `store` is `redis`. | ## Named here - The app says who is calling through one function, `caller(request)`. A request with no caller gets 401 with the code `unauthenticated`. - A key that breaks the rules for a key gets 400 with the code `idempotency_key_invalid`. - The method is in capitals in the fingerprint. - The row that marks a key as in progress is committed on its own, before the handler runs, so that a second request sees it at once. Marking it done commits with the handler's changes. - The note in R7 is a `note` column, and holds `answer_not_kept`. ## What this spec leaves to you Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README. - Not a
-
tasks.mdBuild tasks in order, each with a check.Tasks
Work in order. Finish a task's check before starting the next.
- Set up. A test runner, a clock that tests can set, and the smallest API to put this in front of if there is none: one
POSTroute with a counter and a caller taken from a header. Check: an empty test run passes. - The fingerprint (R2). A pure function. Check: a test reproduces both rows of the table in
design.md. - The store. The fields in
design.mdfor thestoreinput, with the one step that records a key. Check: of 20 attempts at once to record one key, one succeeds. - The header (R1) and the first request (R2). Check: the R1 and R2 acceptance tests pass.
- Again (R3), for something else (R4), two at once (R5). Check: the R3, R4 and R5 acceptance tests pass.
- What is kept (R6) and forgetting (R7). Use the
key_hoursinput. Check: the R6 and R7 acceptance tests pass. - Keys required (R8). Only if
require_keyis on. Check: the R8 acceptance tests pass. - Finish. Write the README and run the whole test suite. Check: every item under "Definition of done" in
spec.mdis true.
# Tasks Work in order. Finish a task's check before starting the next. 1. **Set up.** A test runner, a clock that tests can set, and the smallest API to put this in front of if there is none: one `POST` route with a counter and a caller taken from a header. Check: an empty test run passes. 2. **The fingerprint (R2).** A pure function. Check: a test reproduces both rows of the table in `design.md`. 3. **The store.** The fields in `design.md` for the `store` input, with the one step that records a key. Check: of 20 attempts at once to record one key, one succeeds. 4. **The header (R1) and the first request (R2).** Check: the R1 and R2 acceptance tests pass. 5. **Again (R3), for something else (R4), two at once (R5).** Check: the R3, R4 and R5 acceptance tests pass. 6. **What is kept (R6) and forgetting (R7).** Use the `key_hours` input. Check: the R6 and R7 acceptance tests pass. 7. **Keys required (R8).** Only if `require_key` is on. Check: the R8 acceptance tests pass. 8. **Finish.** Write the README and run the whole test suite. Check: every item under "Definition of done" in `spec.md` is true.
- Set up. A test runner, a clock that tests can set, and the smallest API to put this in front of if there is none: one
Is it for me?
- Kind
- app part
- Platforms
- backend
What does it need?
- Accounts
- A Redis server, if keys are kept in Redis
- Agent permissions
- shell, network
- Secrets it reads
DATABASE_URLREDIS_URL
What changed?
- 0.1.215 Nov 2026Names what it builds.
- 0.1.114 Nov 2026Says "person" where it said "buyer".
- 0.1.014 Nov 2026Moved from dwrtz/idempotency-keys.
For agents: start.md says how to build this spec, spec.json holds everything on this page, and bundle.tar.gz holds its files.