Error Codes
This page describes common response formats for generation and native Chat Series endpoints. Use the HTTP status and the endpoint-specific error body.
Success Response
Generation submission returns a response with code: 200. Native Chat Series responses use their protocol-specific format:
Error Response
Generation endpoints return the HTTP error status with a detail field. They do not wrap errors in code and error:
Native Chat Series Errors
Chat Completions and Responses use an error object; Claude Messages adds type=error; Gemini uses error.code, error.message, and error.status. Authentication failures may still use detail. Upstream error status codes and bodies are forwarded unchanged. Successful JSON responses and SSE events are not wrapped in code and data.
Task Failed Response
When a task fails during processing, the response includes status: "failed" with an error message:
HTTP Status Codes
200 - Success
Request completed successfully. For generation endpoints, check data.status to determine task state. Native Chat Series returns its JSON response or SSE stream directly.
400 - Bad Request
The request contains invalid parameters or data.
Example:
401 - Unauthorized
Missing or invalid credentials. Authentication errors use a detail field.
402 - Payment Required
Native Chat Series endpoints use HTTP 402 for insufficient credits. Generation submission uses HTTP 400 for insufficient credits.
Example:
403 - Forbidden
Access denied due to permission restrictions.
Example:
404 - Not Found
The requested resource does not exist.
Example:
408 - Request Timeout
The request timed out before a response was returned. The timeout middleware returns plain text:
Example:
422 - Unprocessable Entity
Malformed JSON or a request body that is not an object may be rejected before endpoint handling. The detail field is an array of validation errors.
429 - Too Many Requests
Rate limit exceeded.
Example:
500 - Internal Server Error
An unexpected server error occurred.
Example:
502 - Bad Gateway
Upstream service error.
Example:
503 - Service Unavailable
The requested model is temporarily unavailable. Contact support to check model availability before retrying. An unknown or disabled public model normally returns HTTP 404.
Error Handling Best Practices
Retry transient failures carefully: For temporary 500 or 502 errors, use exponential backoff. Retrying submission can create another task. For HTTP 503, contact support to check model availability before retrying.
Handle rate limits: When receiving 429 errors, wait before retrying. Consider implementing request queuing.
Validate inputs: Check your request parameters before sending to avoid 400 errors.
Monitor credits: Generation submission reports insufficient credits as HTTP 400; native Chat Series reports HTTP 402.