Error Codes

Every endpoint returns errors in the same JSON shape:

{
  "error": {
    "message": "Human-readable description, usually with a request ID for debugging",
    "type": "new_api_error",
    "code": "invalid_request"
  }
}

HTTP status codes

Status	Meaning	Common causes
400	Bad request	Malformed body, missing required field, a parameter value the target model doesn't support
401	Unauthorized	Missing Authorization header, invalid/deleted API key
403	Forbidden	Key disabled, account banned, source IP not allowlisted, access policy triggered
404	Not found	Requested a path or resource ID that doesn't exist
429	Too many requests	Quota exhausted, rate limit triggered
500	Internal server error	Gateway-side fault — retry and watch the status page
503	Service unavailable	Load-shedding, failed health check

Common business error codes (error.code)

code	Meaning	Suggested handling
invalid_request	Malformed request/parameters	Check the request body against the endpoint's documented shape
model_not_found	The requested model doesn't exist or isn't currently available	Call GET /v1/models to confirm the correct model name
insufficient_user_quota	Account/key quota exhausted	Top up in the console or raise the key's quota cap
access_denied	Access denied (IP restriction, account state, etc.)	Check the key's IP allowlist and account status
sensitive_words_detected	Content blocked by safety policy	Adjust the request content to comply with content policy
channel:no_available_key	No upstream key currently available on the backing channel	Usually a platform-side channel issue — retry later; report if persistent
bad_response_status_code	The upstream provider returned an unexpected status	The gateway does its best to translate this — treat like a 5xx and retry

More internal codes

Beyond the high-frequency codes above, the gateway defines finer-grained internal/channel error codes (provider-specific rate limits, content-policy differences, etc.) — these are typically described in the message field. If code isn't in this table, read message first, or contact the platform team for help.

Retry guidance

Scenario	Retry?
429 rate limit	Yes — exponential backoff
500 / 503	Yes — brief wait, then retry; alert on repeated failures
401 / 403	No — fix credentials/permissions first
400 (bad params)	No — fix the request content first
model_not_found	No — confirm the correct model name first

Debugging tips

• Keep the request-identifying info from message (usually a request ID) when contacting the platform team — it speeds up investigation.
• Reproduce with curl first to rule out SDK-wrapper issues vs. the API itself.
• Check whether you've hit one of the "not yet supported" cases in OpenAI-Compatible API.

Related

• Making Requests
• FAQ