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) |
| 401 | missing_api_key | No key | Add Authorization: Bearer … |
| 401 | invalid_api_key | Wrong, revoked or expired key | Create a new key in the console |
| 403 | organization_inactive | Organization on the waitlist or suspended | Wait for activation or write to us |
| 404 | model_not_found | Unknown model, or not included in your plan | Check GET /v1/models |
| 429 | rate_limit_exceeded | 5-hour quota used up, or too many concurrent requests | Retry after Retry-After seconds |
| 429 | insufficient_quota | Monthly quota used up | It resets on the 1st of the month; see the console |
| 502 | upstream_error | Model error | 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 |
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.