Error Handling

API error responses and status codes

Error Response Format

All error responses use this structure:

1{
2 "type": "error",
3 "error": {
4 "type": "error_type",
5 "message": "Human-readable error message"
6 }
7}

HTTP Status Codes

400 - Bad Request

Error Type: invalid_request_error

Invalid request parameters or validation errors.

1{
2 "type": "error",
3 "error": {
4 "type": "invalid_request_error",
5 "message": "prompt is required"
6 }
7}

401 - Unauthorized

Error Type: authentication_error

Missing or invalid API key.

1{
2 "type": "error",
3 "error": {
4 "type": "authentication_error",
5 "message": "Missing authorization header"
6 }
7}

422 - Content Filtered

Error Type: content_filtered_error

Content rejected by safety filters.

1{
2 "type": "error",
3 "error": {
4 "type": "content_filtered_error",
5 "message": "Content is filtered due to policy restrictions"
6 }
7}

429 - Too Many Requests

Error Types: rate_limit_error, concurrency_limit_error

Rate limit or concurrency limit exceeded. See Rate Limits for details.

500 - Internal Server Error

Error Type: api_error

Unexpected server error.

1{
2 "type": "error",
3 "error": {
4 "type": "api_error",
5 "message": "Internal server error"
6 }
7}

503 - Service Unavailable

Error Type: service_unavailable

Service temporarily unavailable.

1{
2 "type": "error",
3 "error": {
4 "type": "service_unavailable",
5 "message": "Service temporarily unavailable"
6 }
7}