Errors and rate limits
Error structures, code mappings, retry guidance, and rate limits for both protocols.
Errors follow the protocol you call. OpenAI-compatible endpoints, including /v1/chat/completions, /v1/responses, /v1/embeddings, and /v1/videos, use OpenAI definitions. /v1/messages uses Anthropic definitions. Official SDKs can handle their corresponding exception classes directly.
Error structures
OpenAI-compatible endpoints:
{
"error": {
"message": "Your organization's balance is used up — top up in the console to continue; retrying will not help（组织余额已用完，请在控制台充值后继续；重试无效）",
"type": "insufficient_quota",
"param": null,
"code": "credit_balance_exhausted",
"goodput_reason": "balance_exhausted",
"goodput_scope": "org"
}
}Anthropic-compatible endpoints (/v1/messages, /v1/messages/count_tokens):
{
"type": "error",
"error": {
"type": "billing_error",
"message": "Your organization's balance is used up — …（组织余额已用完…）",
"goodput_reason": "balance_exhausted",
"goodput_scope": "org"
},
"request_id": "5b1d…"
}The example message values deliberately retain both English and Chinese, as returned by the API.
| Field | Description |
|---|---|
error.type / error.code | Follow official OpenAI and Anthropic values; SDKs use them to raise the corresponding exceptions |
error.goodput_reason | A rejection reason shared across both protocols, useful for unified handling; see below |
error.goodput_scope | The budget layer reached by a quota error; see budget errors |
error.message | A bilingual explanation for troubleshooting; do not use it for programmatic decisions |
Error code reference
| Status | goodput_reason | OpenAI type / code | Anthropic error.type | Common cause | Action |
|---|---|---|---|---|---|
| 400 | invalid_request | invalid_request_error | invalid_request_error | Invalid body, missing model / messages, or invalid parameter values | Correct the request using the error details |
| 400 | unsupported_option | invalid_request_error / unsupported_value | invalid_request_error | A model does not provide the requested option, such as a video resolution tier | Use one of the available values listed in the error |
| 400 | context_length_exceeded | invalid_request_error / context_length_exceeded | invalid_request_error (message starts with prompt is too long) | Input exceeds the context window | Shorten input or use a larger-context model |
| 400 | content_policy | invalid_request_error / content_policy_violation | invalid_request_error | Content blocked by a safety policy | Adjust the input |
| 401 | authentication_failed | invalid_request_error / invalid_api_key | authentication_error | Missing, invalid, deleted, expired, or disabled key | Check Authorization: Bearer or x-api-key |
| 403 | permission_denied | invalid_request_error / permission_denied | permission_error | The key cannot access this resource | Check key permissions |
| 404 | model_not_found | invalid_request_error / model_not_found | not_found_error | Model ID missing, not on sale, not enabled for your account, or unsupported by this endpoint | Check the catalog; if the ID is correct, contact support for access |
| 404 | not_found | invalid_request_error / not_found | not_found_error | Resource not found, such as a video task ID | Check the ID |
| 409 | conflict | invalid_request_error / conflict | conflict_error | Current resource state conflicts with the operation, such as downloading an unfinished video | Wait for the state to change |
| 413 | request_too_large | invalid_request_error / request_too_large | request_too_large | Request body exceeds the byte limit | Reduce the body size |
| 429 | balance_exhausted | insufficient_quota / credit_balance_exhausted | billing_error | Funds exhausted, including an arrears freeze | Add funds; service resumes without recreating keys. Retrying does not help |
| 429 | spend_limit_reached | insufficient_quota / see budget errors | billing_error | A key, team, member, or subscription cap is reached, even if funds remain | Raise the relevant cap or wait for its reset. Retrying does not help |
| 429 | rate_limited | rate_limit_error / rate_limit_exceeded | rate_limit_error | Request rate, token rate, or concurrency exceeded | Wait according to retry-after, then retry |
| 500 | internal_error | server_error | api_error | Internal platform error | Retry later |
| 502 | upstream_error | server_error | api_error | Upstream model service error | Retry later, or configure fallbacks |
| 503 | overloaded | service_unavailable_error / server_is_overloaded | — (see next row) | Model overloaded with no available capacity | Wait according to retry-after, then retry |
| 529 | overloaded | — | overloaded_error | Same overload condition; Anthropic uses 529 | Same as above |
| 503 | internal_error | server_error | api_error | Service temporarily unavailable | Retry later |
| 504 | upstream_timeout | server_error / timeout | timeout_error | Upstream model timed out | Retry; use streaming for long outputs |
Exhausted funds return 429, not 402. Rate limits also use 429. Distinguish them using goodput_reason, OpenAI code, or Anthropic error.type: retrying balance or budget errors does not help; rate limits can be retried after retry-after.
Budget errors
balance_exhausted means the charged personal account or organization has run out of funds. spend_limit_reached means a configured limit was reached even though funds may remain. goodput_scope identifies the affected layer:
goodput_scope | Meaning | OpenAI code |
|---|---|---|
org | Organization funds exhausted | credit_balance_exhausted |
account | Personal account funds exhausted | credit_balance_exhausted |
key | This key’s spending cap | api_key_spend_limit_exceeded |
team / project | Team or project cap | project_spend_limit_exceeded |
member | Your membership budget within the team | member_spend_limit_exceeded |
subscription | Subscription quota | subscription_quota_exceeded |
user | Individual member’s cap within the organization | spend_limit_exceeded |
end_user | Cap for an end user identified by the request’s user field | spend_limit_exceeded |
tag | Cap configured for a tag | spend_limit_exceeded |
Retry guidance
Error responses include retry-related headers that official SDKs observe automatically:
x-should-retry: false: retrying is pointless, for example invalid parameters, invalid keys, or exhausted funds/budgets. Official OpenAI and Anthropic SDKs do not retry automatically when this is set.retry-after: recommended wait in seconds for rate limiting or overload.
| Retryable | Not retryable |
|---|---|
rate_limited, overloaded, upstream_timeout, upstream_error, internal_error | All other goodput_reason values, including balance and budget 429 errors |
For cross-model recovery, use the request-level fallbacks parameter so the gateway handles switching.
Errors in streaming requests
- Before any output has been sent, failure returns a normal error response with the actual status code and JSON structure above.
- After output begins, HTTP status is already 200. The error arrives as an event:
data: {"error": {…}}for OpenAI, orevent: errorwith the Anthropic structure above. Official SDKs convert these events into exceptions.
Rate limits
Account and project limits apply to both request frequency and token rate. Organization administrators can configure separate project limits in the console.
Enterprise customers can contact us for higher limits or dedicated quotas.
Reporting a problem
Every error includes a request ID in x-goodput-request-id. OpenAI-compatible responses also provide x-request-id; Anthropic provides request-id and a body request_id. It is the same request_id shown in console request logs. Provide it to support with the time and model ID for faster investigation.