HTTP Idempotency

Deduplicate replays of mutating requests via idempotency keys

Contract-declared retries

// Shared contract: opt in once.
const CreateTodo = endpoint.post('/todos').idempotent().body(CreateTodoSchema);

const client = createClient(api, {
    middlewares: [retry({ limit: 3 }), timeout({ timeout: 10_000 })]
});

// Framework generates a key and retains it across HTTP retries.
await client.todos.create({ body: { title: 'Buy milk' } });

// A new client call represents a new operation and gets a fresh key.

Server Integration

Endpoint preparation runs after authentication and validation, before every replay. It receives typed request data and injected services. Scope resolution uses the prepared request. Concurrent duplicates share one execution within a bounded, process-local store.

server.handle(CreateTodo.authorize(UserPrincipal).inject({ db: DbToken }), createHandler, {
    prepare: authorizeAndResolveWorkspace,
    idempotency: {
        scope: ({ principal, body }) => [principal.userId, body.workspaceId]
    },
    errors: todoErrors
});

// The same options work in implement(api).group(...).withHandlers(...).

How replay works

  • On mutation: Client auto-generates a UUID v4 as X-Idempotency-Key header.
  • On server: First request with a key runs the handler and stores the response. Replays return the stored response immediately.
  • On retry: The key is preserved — retried requests are treated as replays, not new operations.

Low-level middleware options (Client)

API reference table
OptionTypeDefault
headerNamestring"X-Idempotency-Key"
keyGenerator(url, init) => stringuuid v4
condition(url, init) => booleanmutations only

Options (Server)

API reference table
OptionTypeDefault
scope(ctx) => string | undefinedRequired; undefined skips replay
maxEntriesnumber1000 (pending and completed)
maxResponseBytesnumber65536 bytes
ttlnumber86400000 (24h)
headerNamestring"x-idempotency-key"
skip(ctx) => booleannon-mutating requests