Idempotency
Send an idempotency key with retry-sensitive requests so a safely retried request runs at most once. When a key is reused after a non-streaming request completed, Keiro replays the original response instead of executing the request again. A reused key that Keiro still holds but cannot replay is refused; see Conflicts. A request that failed before any billable work does not hold its key, so reusing that key runs the request again.
On this page 1 of 8
When to use idempotency keys#
Use an idempotency key when a network error, timeout, or client retry could resend a request you do not want to run twice. Generate a unique key for each logical operation, reuse the same key when you retry that operation, and use a new key for a new operation.
Send an idempotency key#
Set the Idempotency-Key request header on the request. With the OpenAI-compatible SDKs, pass it as a per-request custom header. You may also send an idempotency_key field in the JSON body. If you send both, they must be equal, or the request is rejected with 400.
A key is any non-empty string. An empty Idempotency-Key header, or one of only whitespace, is refused with 400. In the body, Keiro does not trim the key: an idempotency_key field that is empty, only whitespace, or has leading or trailing whitespace is refused with 400, and so is one that is present, not null, and not a JSON string. A null body field counts as no key. Keiro sets no length limit of its own, but the header counts toward HTTP header size limits, so keep keys short. Use a value that is unique per operation, such as a UUID. Keys are scoped to your organization, so the same key value used by a different organization never collides with yours.
Replay behavior#
The first non-streaming request to complete with a given key stores its response for replay, unless the response is too large to store. A later request that reuses the key with the same endpoint and request body receives the stored response instead of running again. Keiro stores nothing for a request with stream: true, so a stream is never replayed.
| Response header | Meaning |
|---|---|
X-Idempotent-Replay: true | The response is a replay of an earlier request, not a new run |
X-Original-Request-Id | The request id of the original request that produced the stored response |
A replay returns the original status code and body. Retry-sensitive side effects, including usage billing, happen once for the original request.
Conflicts#
Keiro returns 409 with code idempotency_key_conflict when a reused key is still held and no stored response can be replayed. The response carries an X-Original-Request-Id header pointing to the original request when Keiro knows it. This happens when:
- The key was used with a different endpoint or a different request body.
- The first request is still running. Once a non-streaming request completes, its stored response can be replayed with the same key.
- The first request used
stream: true, even after the stream completed. - The first response was too large to store.
- The first request failed after it recorded billable usage, or after a hosted web search or document processing had started.
Use a new key when the request is genuinely different. Resending the exact original request returns a replay only when one was stored.
Retention#
Stored keys and replays are short-lived operational state. A key is replayable for up to 24 hours after it first completes. After it expires, the same key value starts a new operation. See Data retention for the retention posture.
Example#
printf 'Keiro API key: '
IFS= read -rs KEIRO_BEARER
printf '\n'
curl -sS https://api.keirolabs.ai/v1/responses \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5f3b8c9a-2d1e-4a7b-9c0f-6e2a1b4d7c88" \
-d '{
"model": "eb1-preview",
"input": "Summarize the incident report."
}' \
-H @- <<<"Authorization: Bearer $KEIRO_BEARER"
Once the request has completed successfully, resend the same command with the same Idempotency-Key to receive the original response with X-Idempotent-Replay: true.
Compatibility notes#
- Idempotency applies to
POSTrequests on the completion endpoints,/v1/chat/completions,/v1/responses, and/v1/messages. Replay applies to non-streaming requests only. - Treat
409 idempotency_key_conflictas a client error; do not retry it without changing the key or the request. See Errors.