Skip to main content

​
Idempotency keys

An idempotency key is a stable name for a unit of work. Same key = same operation. You own the key and idem0 uses it verbatim — it never generates one for you. Good keys come from something already stable in your system:
  • a job id from your queue
  • a step id in an agent run
  • a hash of the inputs that define the work
Reuse the key on a retry and idem0 knows it’s the same call. Use a fresh key when it’s genuinely new work.

​
Replay

The first call for a key runs for real and idem0 stores the response (encrypted). Every later call with that key replays — idem0 returns the stored response byte-for-byte and tags it:
A replay never hits the model, so it costs 0 credits and returns immediately. Your retries, resumes, and redeliveries stop double-paying and stop drifting to a different answer. Replays are available for 30 days after the first call. After that the record expires and the same key runs fresh again.

​
Same key, different request

A key is a promise that the request is the same. If you send the same key with a different body, idem0 rejects it with 422 Unprocessable rather than return the wrong cached answer. Send a key only for the request it belongs to. If two identical calls race — the same key arrives while the first is still running — the second gets 409 Conflict. Retry it once the first finishes and you’ll get the replay.

​
BYOK

idem0 is bring-your-own-key. Your provider token lives in your provider SDK and travels on its normal auth header (x-api-key for Anthropic, Authorization: Bearer for OpenAI). idem0 forwards it upstream untouched and never stores or logs it. The only credential idem0 owns is your x-idem0-key.

​
Streaming works too

Streaming responses are idempotent the same way: the first stream is captured as it flows, and a replay re-emits the same stream, tagged idem0-idempotent-replayed: true. Use the same key you’d use for a non-streaming call.