| Code | Type | Meaning | How to fix |
|---|---|---|---|
| 400 | invalid_request_error | Malformed request body, missing required field, or unsupported parameter. | Verify JSON validity and required fields (model, messages). Check the API reference for supported parameters. |
| 400 | content_policy_violation | Input was blocked by content safety guardrails. | Review the input for prohibited content and retry with compliant text. |
| 401 | authentication_error | API Key missing, malformed, or revoked. | Re-copy the key from your dashboard. Confirm Authorization: Bearer <key>. |
| 402 | insufficient_balance | Account balance exhausted, key monthly budget reached, or team spend limit hit. | Top up in Dashboard → Billing, raise the key's monthly budget, or contact your team admin. |
| 403 | model_not_allowed | The model is not in this key's whitelist. | Edit the key whitelist to include the model, or use a key with broader access. |
| 403 | account_suspended | The account has been suspended. | Contact support to resolve the suspension. |
| 403 | ip_not_whitelisted | Request originated from an IP not in the key's allowed list. | Add the IP to the key's IP whitelist in /dashboard/keys, or use a key without IP restrictions. |
| 403 | referrer_not_allowed | The HTTP Referer header is not in the key's allowed referrers. | Add the referrer domain in /dashboard/keys, or remove the referrer restriction. |
| 403 | feature_not_available | The requested feature requires a higher plan tier. | Upgrade your plan in Dashboard → Billing, or switch to a supported capability. |
| 404 | not_found_error | Unknown model id, or the model is not currently available. | Check spelling on /models or via GET /v1/models. The error.code field provides the specific reason (e.g. model_not_found). |
| 405 | invalid_request_error | The HTTP method is not allowed for this endpoint. | Check the API reference for the correct method (usually POST or GET). The error.code is method_not_allowed. |
| 413 | request_too_large | Request body too large, or input exceeds the model's context window. | Trim history, chunk the input, or switch to a longer-context model (qwen3-max, gpt-4-1). Chat body max 10 MB. |
| 415 | invalid_request_error | Content-Type must be application/json. | Set Content-Type: application/json header on the request. The error.code is unsupported_media_type. |
| 429 | rate_limit_error | Too many requests for this account or key per minute. | Retry with exponential backoff (start at 1s, add a small random delay, cap at 60s). Contact sales if you need a higher sustained limit. |
| 500 | api_error | Unexpected error inside SeaLink. | Check /status. Retry once. If persistent, contact support with the request ID. |
| 502 | api_error | Upstream model returned an error or timed out. Covers upstream 5xx, connection failures, and timeouts. | Retry once with backoff. If it persists, switch to another model or contact support. |
| 503 | overloaded_error | SeaLink is temporarily unavailable (overloaded, in maintenance, or billing circuit open). | Check the status page and retry with backoff. If it persists, contact support with the request ID. |
About timeout errors
Upstream timeouts do not return separate 408 or 504 codes. All upstream timeouts, connection failures, and upstream 5xx responses are surfaced as 502. This matches OpenAI's behavior — your SDK can handle upstream failures uniformly via type: "api_error".
About 403 errors
403 covers several access control scenarios. Check the error.type field to distinguish: model_not_allowed (model whitelist), account_suspended (account suspended), ip_not_whitelisted (IP restriction), referrer_not_allowed (referrer restriction), or feature_not_available (plan tier limit).