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?

Idempotent API requests: desk readyIdempotent API requests: first chargeIdempotent API requests: replayed chargeIdempotent API requests: reused key

What can I customize?

Where keys are kept The database lets a key be saved in the same transaction as the work.

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.md Requirements 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.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.
    # 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.
    

    Open spec.md as plain text

  • design.md Data 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 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.

    MethodPathBodyFingerprint
    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

    FieldHolds
    scopeThe caller: an API key's id or a user's id
    keyThe header's value
    fingerprintAs above
    statein_progress or done
    status, headers, bodyThe answer, once done
    locked_until60 seconds after the key was recorded
    expires_atkey_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:
    storeThe one step
    databaseAn INSERT that does nothing on conflict, then a check of whether a row was written
    redisSET with NX and an expiry
    1. If it was recorded, run the handler, then store the answer or release the key as R6 says.
    2. If the key was already there, read it:
    What is thereAnswer
    ExpiredDelete it and go back to step 3
    Different fingerprint422 idempotency_key_reused
    doneThe stored answer, with Idempotent-Replayed: true
    in_progress, locked_until passedTake the key over with one conditional update, then step 4
    in_progress409 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

    {
      "error": {
        "code": "idempotency_key_reused",
        "message": "This key was used for a different request."
      }
    }

    Configuration

    SecretPurpose
    DATABASE_URLConnection string, when store is database.
    REDIS_URLConnection 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.

    # 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.
    

    Open design.md as plain text

  • tasks.md Build tasks in order, each with a check.

    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.
    # 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.
    

    Open tasks.md as plain text

Is it for me?

Platforms
backend

What does it need?

Accounts
A Redis server, if keys are kept in Redis
Agent permissions
shell, network
Secrets it reads
DATABASE_URL REDIS_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.