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-Keyheader. - 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)
| Option | Type | Default |
|---|---|---|
headerName | string | "X-Idempotency-Key" |
keyGenerator | (url, init) => string | uuid v4 |
condition | (url, init) => boolean | mutations only |
Options (Server)
| Option | Type | Default |
|---|---|---|
scope | (ctx) => string | undefined | Required; undefined skips replay |
maxEntries | number | 1000 (pending and completed) |
maxResponseBytes | number | 65536 bytes |
ttl | number | 86400000 (24h) |
headerName | string | "x-idempotency-key" |
skip | (ctx) => boolean | non-mutating requests |