Idempotency
idempotency-key is accepted on POST /v1/tasks, POST /v1/embeddings and POST /v1/rerank, and, where they are offered, on POST /v1/uploads, POST /v1/files, POST /v1/batches and POST /v1/batches/{batch_id}/cancel; its value is the client's, up to a length Not decided yet, scoped to the key. A replay of an upload, a file or a batch carries idempotent-replayed: true. The SDK generates one per task call.
| Rule | Behavior |
|---|---|
| First request | Served; the key, a keyed hash of the body and the requirement headers, and the request's state are kept for the window Not decided yet. No answer is kept |
| Same key, same body, after a task, embeddings or rerank request completed | 404 result_expired, its message naming the first request's req_ id. Nothing runs, nothing is billed again |
| Same key, different body | 400 idempotency_key_reused |
| Same key while the first is still being answered | 400 idempotency_in_progress |
| A replay of an upload, a file or a batch | Answers the object as it now is, read from its record, with idempotent-replayed: true; a replayed file upload stores nothing twice |
| Not on chat completions, Responses or Messages | POST /v1/chat/completions, /v1/responses and /v1/messages take no idempotency-key: a replay would need the gateway to store a completion body, which it never does. A retried completion is a new request, a new quote and a new charge |
- Rule
- First request
- Behavior
- Served; the key, a keyed hash of the body and the requirement headers, and the request's state are kept for the window Not decided yet. No answer is kept
- Rule
- Same key, same body, after a task, embeddings or rerank request completed
- Behavior
- 404
result_expired, its message naming the first request'sreq_id. Nothing runs, nothing is billed again
- Rule
- Same key, different body
- Behavior
- 400
idempotency_key_reused
- Rule
- Same key while the first is still being answered
- Behavior
- 400
idempotency_in_progress
- Rule
- A replay of an upload, a file or a batch
- Behavior
- Answers the object as it now is, read from its record, with
idempotent-replayed: true; a replayed file upload stores nothing twice
- Rule
- Not on chat completions, Responses or Messages
- Behavior
POST /v1/chat/completions,/v1/responsesand/v1/messagestake noidempotency-key: a replay would need the gateway to store a completion body, which it never does. A retried completion is a new request, a new quote and a new charge
- Generate the key before the first attempt and reuse it on every retry of the same body.
- Treat a 400
idempotency_in_progressas a signal to wait and retry with the same key, not as a failure. - A different body with the same key is a 400
idempotency_key_reused: a bug in the caller, never retried. - A task, embeddings or rerank request that completed is never answered again: a retry with its key answers 404
result_expired, naming the first request'sreq_id, so keep the answer you received. - A replay of an upload, a file or a batch carries the original
x-hips-request-id, so the Console shows one request and one charge.
Related sheets
- Sheet
- 19 of 20
- Detail
- D
- Updated
- 2026-11-14