Idempotency

Send an idempotency key with retry-sensitive requests so a safely retried request runs at most once. When a key is reused, Keiro replays the original response instead of executing the request again.

Copy Page https://docs.keirolabs.ai/idempotency.md

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 with no leading or trailing whitespace. 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 request to complete with a given key stores its response for replay. A later request that reuses the key with the same endpoint and request body receives the stored response instead of running again.

A replay returns the original status code and body. Retry-sensitive side effects, including usage billing, happen once for the original request.

Conflicts#

If you reuse a key with a different endpoint or a different request body, Keiro returns 409 with code idempotency_key_conflict and an X-Original-Request-Id header pointing to the original request. Use a new key when the request is genuinely different, or resend the exact original request to get a replay.

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#

1
2
3
4
5
6
7
8
9
10
11
12

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"

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.
• Treat 409 idempotency_key_conflict as a client error; do not retry it without changing the key or the request. See Errors.

Related pages#

• Errors
• Streaming
• Data retention