Errors
Errors follow the OpenAI format, so the SDKs turn them into their exceptions (AuthenticationError, RateLimitError and so on):
{
"error": {
"message": "…",
"type": "rate_limit_error",
"param": null,
"code": "rate_limit_exceeded"
}
} | HTTP | code | When | What to do |
|---|---|---|---|
| 400 | invalid_request | Invalid parameters, n other than 1, max_tokens above the maximum, context too long | Fix the request (see param and message) |
| 400 | request_too_large | A request larger than the plan reads at once (Free: about 30,000 tokens) | Shorten the messages or move to a paid plan |
| 401 | missing_api_key | No key | Add Authorization: Bearer … |
| 401 | invalid_api_key | Wrong or revoked key | Create a new key in the console |
| 401 | api_key_expired | The key has expired: the message says when | Create a new key in the console |
| 403 | organization_inactive | Organization on the waitlist or suspended | Wait for activation or write to us |
| 403 | terms_not_accepted | Signed in with an account (not an API key) that has not accepted the terms and acceptable use rules yet | Accept them in the chat or the console |
| 403 | api_not_in_plan | API key of an organization on the Free plan, which includes the Chat only | Move to the Plus plan or above |
| 403 | model_not_allowed | Model reserved to verified organizations, or to the Extreme add-on on paid plans | Ask for verification in the console, Plan page |
| 404 | model_not_found | Unknown model, or not included in your plan | Check GET /v1/models |
| 429 | rate_limit_exceeded | 5-hour or 7-day quota used up, or too many concurrent requests | Retry after Retry-After seconds |
| 429 | insufficient_quota | Quota of the month or of the 30-day period used up | It resets on the 1st of the month or at renewal; see the console |
| 429 | too_many_failed_requests | Too many failed requests from the same address (wrong key, paths that do not exist): 30 in 10 minutes | Fix the key and retry after Retry-After seconds |
| 502 | upstream_error | Model error | Retry; if it repeats, write to us with x-request-id |
| 500 | internal_error | An unexpected error on our side | Retry; if it repeats, write to us with x-request-id |
| 503 | server_overloaded | Queue full or wait too long | Retry after Retry-After (the SDKs do it for you) |
| 503 | model_unavailable | Model temporarily unavailable | Retry after Retry-After |
| 503 | safety_unavailable | The red-line check is not answering: to stay safe we don’t proceed | Retry shortly |
| 503 | upstream_unavailable | The model cannot be reached | Retry after Retry-After |
| 503 | auth_unavailable | Signed in with an account (not an API key): the sign-in system does not answer | Retry after Retry-After |
| 504 | upstream_timeout | The model did not start answering in time | Retry |
Retrying
- Every 429 and 503 carries
Retry-After(seconds). - When a quota is used up we add
x-should-retry: false: the OpenAI SDKs won’t retry by themselves, because the wait can be hours. - For 503s the SDKs retry with growing waits: that’s fine.
- If 5xx errors last, check status.beatriceai.it: it shows the state of the API, the model and sign-in, and ongoing incidents.
Red-line refusals
They are not errors: the response is normal (HTTP 200) with finish_reason: "content_filter" and a text naming the rule that applies. See Red lines.