Error Codes and Error Handling

18. Error Codes and Error Handling#

On failure, the API returns an OpenAI-compatible error structure (the /v1/messages endpoint returns an Anthropic-shaped error structure):

JSON

{
  "error": {
    "message": "错误描述",
    "type": "invalid_request_error",
    "code": 400
  }
}

Status code	Meaning	Troubleshooting
`400`	Missing or invalid request parameters	Check required fields such as `model`, `messages`, `input`; do not send tools / multimodal content to `/v1/messages`
`401`	Missing or invalid API Key	Confirm the `Authorization: Bearer sk-...` header is correct and the key is not expired / revoked
`402`	Quota exhausted or insufficient balance	Top up in the console or adjust the key's quota
`403`	Source IP not on the allowlist	Check the key's IP allowlist settings
`404`	Model does not exist or is not accessible / task does not exist	Confirm available models with `GET /v1/models`; confirm the path carries a single `/v1`
`429`	Rate limit triggered	Lower concurrency, then retry with exponential backoff
`500`	Internal gateway error	Retry later; contact support if it persists
`502`	Upstream vendor returned an error	Retry later or switch models
`503`	No available channel	No upstream is currently available for this model; retry later or contact support

Retry 429 and 5xx automatically (exponential backoff + a maximum retry count).
Do not retry client errors such as 400, 401, 403 — fix the request instead.
Log the X-Request-Id from the response (if present) so you can provide it to the support team when troubleshooting.