Reference

Idempotency

Send a request again after a timeout and pay one time only. An Idempotency-Key works on the chat completions, Messages and Responses endpoints.

After a network timeout, you do not know if the request completed. Send an Idempotency-Key header, and then a retry is safe. The header works on /v1/chat/completions, /v1/messages and /v1/responses.

curl Python

curl https://api.kontinentai.com/v1/chat/completions \
  -H "Authorization: Bearer $KONTINENT_API_KEY" \
  -H "Idempotency-Key: 8f2a1c94-6e3b-4d5a-9c11-2f7e0a1b3d44" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001","messages":[{"role":"user","content":"Hello"}]}'

import uuid

key = str(uuid.uuid4())   # generated ONCE, reused across every retry of this request

reply = client.chat.completions.create(
    model="claude-haiku-4-5-20251001",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={"Idempotency-Key": key},
)

Make the key one time, before the first try. Use the same key for each retry of that request. A new key for each retry gives no protection.

What happens when you send the key again

Situation	Response
Same key, same body, and the first request completed	The first response again, with the header `Idempotent-Replay: true`. We do not charge for it
Same key, same body, and the first request did not complete yet	`409`. Wait a short time and try again
Same key, different body	`422`. One key is for one request
Same key, more than 24 hours later	We use it as a new key. We keep keys for 24 hours

A repeated response is the same as the first response, with the same id, token counts and cost. We do not run the request again.

Two rules that make it safe

A failed request releases its key. You can retry immediately with the same key.
A key that does not complete in five minutes becomes available again. A request that stops without an answer does not lock the key.

The database records each key. Thus, if two retries arrive at the same time, only one of them runs.

Not with a stream

A request with stream: true and an Idempotency-Key header gets a 400 error with the code idempotency_unsupported_for_stream. To repeat a stream, we would have to keep each streamed response. We refuse the header, so that you do not think that you have a protection that you do not have.

When to use it

Use it on each request where a double charge is a problem and a retry can occur: a queue worker, a webhook handler, or a call through a proxy with its own timeout. It adds no cost when the first try succeeds.