Idempotency
Idempotency
A network timeout does not tell you whether the work happened. Send an Idempotency-Key and a retry returns the original answer instead of generating — and charging for — a second one.
# Same key + same body within 24h => the stored reply, charged once. # The replay carries `idempotent-replay: true`. curl https://api.oxyy.ai/v1/images/generations \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OXYY_API_KEY" \ -H "Idempotency-Key: order-4417-thumbnail" \ -d '{"model": "gpt-image-2", "prompt": "A red bicycle"}'
response = client.images.generate( model="gpt-image-2", prompt="A red bicycle", extra_headers={"Idempotency-Key": "order-4417-thumbnail"}, )
| Rule | Detail |
|---|---|
| Where it applies | Every billable POST: chat completions, responses, messages, images, audio, video and embeddings. |
| How long | A finished reply is replayable for 24 hours. |
| Same key, same body | The stored reply is returned with idempotent-replay: true, and you are charged once. |
| Same key, different body | Refused with 409. Use a new key. |
| Still in flight | Refused with 409 while the first attempt is running. Retry shortly. |
| What is never stored | Authentication failures, rate-limit refusals and server errors — so a retry after one of those really does retry. |
| Streaming | Not covered: a stream cannot be replayed, so the header is ignored on stream: true. |
| Scope | Keys are scoped to the credential that sent them, so two customers cannot collide on the same key. |