Idempotency

Mutating endpoints (POST, PATCH, DELETE) accept an optional Idempotency-Key header. The first request with a given key is processed normally; subsequent requests with the same key replay the cached response for 24 hours without re-executing the handler.

When to use it

Any code path that retries on network errors should send an idempotency key — UUID v4 is the recommended shape, but any opaque string up to 255 bytes works. Without a key, a POST that timed out mid-flight is indistinguishable from a POST that never started, and your retry might create two resources.

Replay semantics

Replays return the full original response body, status code, and headers, plus an X-Idempotency-Replay: true header so the caller can distinguish "I just did this" from "you already did this." The 24-hour cache is keyed by (token_id, idempotency_key) — different tokens with the same key are independent.

Conflicts

If the same key is sent with a meaningfully different request body within the 24-hour window, the API returns 409 with code: idempotency_conflict. The conservative read is "treat the key as already consumed and pick a new one"; the deeper read is "something in my retry logic is generating divergent payloads, investigate."

See also: Errors for the full envelope shape.