Request IDs

Request IDs

Every response, including errors, has an X-Request-ID header like req_6f1c…, also returned as error.request_id. Log it. It opens the request in Logs and works with GET /v1/requests/:id.

Idempotent retries

Without an idempotency key, retrying a request that timed out can start, and bill, a second generation. Send an Idempotency-Key generated once per logical operation:

Idempotency-Key: 8d7e2c4a-6b1f-4f3e-9a51-0c2b7d1e6f90

• Same key, same body, still running: 409 request_in_progress with the original request id.
• Same key, same body, finished: 409 result_not_replayable. No new generation starts, and the response isn't replayed, because responses aren't kept for replay: read the original request's receipt for its outcome and charge.
• Same key, different body: 409 idempotency_conflict. A request from another project or environment counts as a different body.

When the body matches, the 409 also carries original_request_id and receipt, the path to the original's receipt. All three carry the X-Original-Request-ID header.

{
  "error": {
    "code": "result_not_replayable",
    "message": "Original request completed; content is not retained. Retrieve its receipt at /v1/requests/{id}",
    "request_id": "req_91ab…"
  },
  "original_request_id": "req_6f1c…",
  "receipt": "/v1/requests/req_6f1c…"
}

Keys are scoped to your team and endpoint: the same key on /v1/chat/completions, /v1/messages and /v1/responses is three different keys. Use a new key for every new operation, and keep reusing one only for retries of that operation; a key is remembered for 24 hours, and after that it runs a new request. Idempotency keys apply to chat completions, Messages and Responses, and to the management API's creating calls (creating keys, rotating them and adding webhooks), where a matching retry names what the original made in original_id instead of a receipt.

Your own ids

Send X-Client-Request-ID to record an id from your own system on the receipt, such as the job or ticket the call was made for. Chat completions, Messages, Responses, embeddings and evaluations record it.

To group the requests of one conversation or job, send the same ib-session header on each. Logs then show them together (session = …, or GROUP BY session), and GET /v1/usage filters by it. See Sessions.

To attribute cost to your own customers and features, send ib-user with your end user's id and ib-tags with what the request was for. See End users and tags.