Errors and retries
Retry safely with canonical idempotency keys and handle customer-safe errors without relying on private provider details.
Use one UUID v4 per logical request
Idempotency-Key is optional for Chat Completions so standard OpenAI-compatible SDKs work without custom headers. When omitted, OurToken generates a UUID v4 for the request and returns it in the response header.
For retry-safe recovery after an uncertain response, send a canonical lowercase UUID v4 such as 9b97755f-6a36-4a6f-a682-5aa22a67ac47.
If a network timeout leaves the result uncertain, repeat the same authenticated request with the same key. OurToken binds the key to your API key and a fingerprint of the normalized request, so it can recover the same operation without creating a second reservation or charge.
Do not reuse a key for new input
Changing the model, messages, or bounded request parameters while reusing a key produces an idempotency_conflict response. Generate a new UUID v4 for every new logical request.
Handle availability as a product-level state
When no compatible active route can serve a public model, the API returns model_unavailable. The response intentionally avoids exposing provider accounts, route IDs, credentials, or raw upstream errors. Your application can retry with backoff, let a user choose another public model, or defer work.
Common request errors
| Code | Meaning | Next action |
|---|---|---|
invalid_idempotency_key | A supplied request key is malformed. | Omit it or send a canonical lowercase UUID v4. |
idempotency_conflict | A request key was used with different input. | Generate a new key for the new request. |
model_unavailable | The requested public model cannot be served now. | Retry later or offer a different model. |
unauthorized | The key is missing, invalid, or revoked. | Check deployment secrets and key status. |
Retry the same request, not just the same URL
Reuse an idempotency key only when the authorization scope and normalized request are unchanged. A key is a request identity, not a general cache token.