Errors
HTTP status codes, the error body, and which errors to retry.
Errors come back with a non-2xx status and a JSON body in the OpenAI format:
{
"error": {
"message": "Invalid token (request id: 2026100912391754811973...)",
"type": "new_api_error",
"code": ""
}
}Branch on the HTTP status (and error.code when it is not empty). The message is for humans and may change.
Errors raised by the upstream provider after your request is accepted can arrive in that provider's own shape; on /v1/messages that is the Anthropic format, { "type": "error", "error": { "type": "...", "message": "..." } }. Both shapes carry error.message.
Status codes
| Status | Meaning | What to do |
|---|---|---|
400 | The request is malformed. | Fix the request body. |
400 with code: invalid_parameter_error on kimi-k3 | The model accepts only fixed sampling values, and your client sent another one, often a default such as temperature 0.7 or top_p 0.9. The message names it: Parameter 'temperature'=0.7 is not supported for kimi-k3 model. | Leave temperature and top_p out, or set temperature 1 and top_p 0.95. See Sampling limits. |
401 | The key is missing, invalid, expired or has used up its budget. | Check the key in the console. |
403 | The key is not allowed this call (model or IP allowlist), or your balance is too low. | Adjust the key's options or top up. |
429 | Too many requests. | Retry with exponential backoff. See Rate limits. |
503 with code: model_not_found | No upstream serves this model ID. | Check the model ID in the catalog. |
500, 502, 503, 504 | The gateway or the upstream provider failed. | Retry with backoff. |
Requests rejected with 4xx before reaching a model are not charged.
Request IDs
Every response has an X-Oneapi-Request-Id header, and error messages repeat the ID. Include it when you contact support.