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 headerMeaning
X-Idempotent-Replay: trueThe response is a replay of an earlier request, not a new run
X-Original-Request-IdThe 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#

Run a curl request Shell
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 POST requests on the completion endpoints, /v1/chat/completions, /v1/responses, and /v1/messages. Replay applies to non-streaming requests only.
  • Treat 409 idempotency_key_conflict as a client error; do not retry it without changing the key or the request. See Errors.

Search Keiro docs

Start typing to search pages and sections.

Start typing to search pages and sections.

Documentation

Console