Errors
Every error is the OpenAI envelope:
{ "error": { "message": "...", "type": "invalid_request_error", "code": "insufficient_credit" } }Branch on code. The message is written for a human and may be reworded; the code is the contract, and every code this API can answer with is below, in three groups.
What you sent
The request is the thing to change. Sending it again unchanged answers the same way.
| Code | HTTP | Meaning |
context_overflow | 400 | The conversation fills the context your plan serves. Compact it. |
handle_invalid | 400 | A handle is 3 to 32 characters of letters, digits, dot, dash or underscore. |
invalid_cursor | 400 | The sync cursor is not an RFC3339 timestamp. |
invalid_json | 400 | The body is not JSON. |
invalid_request | 400 | The body is missing something required. |
invalid_role | 400 | A message role must be user or assistant. |
password_short | 400 | A password is at least ten characters. Length is the only rule. |
topup_too_small | 400 | That is below the smallest purchase of usage worth taking. |
unknown_interval | 400 | Billing is weekly or monthly; that is neither. |
unknown_rail | 400 | That payment method is not offered by this deployment. |
unknown_tier | 400 | That plan does not exist. |
unauthorized | 401 | Missing or invalid credential. |
unsigned | 401 | That webhook delivery is not signed by the rail it claims to be from. |
account_required | 403 | Image generation needs an account. Chat, code and search do not. |
nothing_to_cancel | 403 | That plan does not renew, so there is nothing to cancel. |
plan_required | 403 | A capability your plan does not include: image generation is on Pro and up, the API on Max. |
scope_required | 403 | This API key is scoped to chat and the route it asked for spends cash. |
key_not_found | 404 | No such key. |
not_found | 404 | No such endpoint, file or record. |
session_not_found | 404 | No such conversation. |
unknown_checkout | 404 | No such checkout attempt. |
handle_taken | 409 | That handle already exists. |
not_a_guest | 409 | This session already has credentials, so there is nothing to claim. |
not_paid | 409 | The rail does not report that attempt as paid. |
nothing_to_carry | 409 | There is no paid period to carry across, which makes this a purchase rather than a switch. |
pair_taken | 409 | That name and password together already open an account. The pair has to be one account or neither could be recovered, so pick a different password. |
period_over | 409 | That subscription has ended; starting again is a purchase rather than a resume. |
same_tier | 409 | The account is already on that plan, so there is nothing to move it to. |
file_too_large | 413 | That file is larger than a workspace accepts. |
provider_refused | 422 | The image model refused this prompt. It is not the one refusal that is ours. |
refused | 422 | The one content constraint, on image generation only. |
challenge_required | 428 | The request has to carry a solved challenge. The refusal names one; solve it and send the answer with the same request. Making an account is always charged; signing in only once an address has missed enough to look like guessing. |
What your plan allows
Nothing is wrong with the request. The allowance behind it is spent.
| Code | HTTP | Meaning |
insufficient_credit | 402 | The plan's usage is spent. |
spend_limit_reached | 402 | Your own daily extra-usage limit would be passed. |
weekly_allowance_reached | 402 | The plan's images or lookups for this week are used. Extra usage carries on past it. |
rate_limited | 429 | Too many free sessions from here today. |
What failed on our side
Not the caller's to fix, and retrying is reasonable.
| Code | HTTP | Meaning |
internal | 500 | Something failed on our side. |
generation_failed | 502 | The image could not be generated. |
upstream_unavailable | 502 | The model is not reachable. Nothing was charged. |
closed | 503 | The operator has stopped new turns and new purchases. What was already running is finishing, and everything that only reads still answers. |
no_isolation | 503 | The sandbox could not isolate the run, so it did not run. |
provider_unavailable | 503 | Image generation is down on our side. Nothing was charged. |
unavailable | 503 | A limit could not be checked, so the request was refused rather than given away. |