Error Codes

This page documents all possible API response codes and error types.

Response Format

Success Response

When a request is successful, the API returns a response with code: 200:

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "not_started",
    "created_time": "2025-11-12T10:30:00"
  }
}

Error Response

When an error occurs, the API returns a response with the corresponding error code:

{
  "code": 400,
  "error": {
    "message": "task_id is required",
    "type": "validation_error"
  }
}

Always read the code field in the response body. Some validation errors from POST /api/generate/submit are returned with HTTP status 200 and "code": 400 in the body. Treat the request as failed whenever code is not 200.

Task Failed Response

When a task fails during processing, the response includes status: "failed" with an error message:

{
  "code": 200,
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8",
    "status": "failed",
    "files": [],
    "created_time": "2025-11-25T08:50:13",
    "error_message": "The prompt violates our content policy"
  }
}

Business Status Codes

200 - Success

Request completed successfully. Check the status field in the response to determine task state.

400 - Bad Request

The request contains invalid parameters or data.

Type	Description
`validation_error`	Parameter validation error
`content_moderation_error`	Content moderation error
`content_too_long_error`	Content exceeds maximum length
`file_format_error`	Invalid file format

Example:

{
  "code": 400,
  "error": {
    "message": "task_id is required",
    "type": "validation_error"
  }
}

401 - Unauthorized

The API key is missing, malformed, or invalid.

Type	Description
`authentication_error`	Missing or invalid API key

Example:

{
  "code": 401,
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error"
  }
}

Check that the request sends Authorization: Bearer YOUR_API_KEY (or x-api-key for /v1/messages), with no extra spaces, and that the key has not been deleted.

402 - Payment Required

Insufficient account balance or credits.

Type	Description
`insufficient_credits_error`	Insufficient credits

Example:

{
  "code": 402,
  "error": {
    "message": "Insufficient credits to complete this request",
    "type": "insufficient_credits_error"
  }
}

403 - Forbidden

Access denied due to permission restrictions.

Type	Description
`permission_denied_error`	Permission denied

Example:

{
  "code": 403,
  "error": {
    "message": "You do not have permission to access this resource",
    "type": "permission_denied_error"
  }
}

404 - Not Found

The requested resource does not exist.

Type	Description
`resource_not_found_error`	Resource not found

Example:

{
  "code": 404,
  "error": {
    "message": "Task not found",
    "type": "resource_not_found_error"
  }
}

408 - Request Timeout

The request took too long to process.

Type	Description
`timeout_error`	Request timeout

Example:

{
  "code": 408,
  "error": {
    "message": "Request timed out",
    "type": "timeout_error"
  }
}

429 - Too Many Requests

Rate limit exceeded.

Type	Description
`rate_limit_error`	Rate limit exceeded

Example:

{
  "code": 429,
  "error": {
    "message": "Rate limit exceeded. Please try again later.",
    "type": "rate_limit_error"
  }
}

500 - Internal Server Error

An unexpected server error occurred.

Type	Description
`internal_error`	Internal server error

Example:

{
  "code": 500,
  "error": {
    "message": "An internal error occurred. Please try again later.",
    "type": "internal_error"
  }
}

502 - Bad Gateway

Upstream service error.

Type	Description
`upstream_error`	Upstream service error

Example:

{
  "code": 502,
  "error": {
    "message": "Upstream service unavailable",
    "type": "upstream_error"
  }
}

503 - Service Unavailable

The service is temporarily unavailable.

Type	Description
`service_error`	Service unavailable

Example:

{
  "code": 503,
  "error": {
    "message": "The server is busy. Please try again later.",
    "type": "service_error"
  }
}

LLM Endpoint Errors

The LLM endpoints (/v1/chat/completions, /v1/responses, /v1/messages, /v1beta/models/{model}:{method}) return errors with a real HTTP status code. Authentication errors use the same body as above. Other errors follow the shape of each API format:

HTTP status	When	Example body
400	A required field is missing or invalid	`{"code": 400, "error": {"message": "Invalid request parameters: messages: Field required", "type": "validation_error", "details": {"validation_errors": [...]}}}`
400	The model does not support this API format	`{"error": {"message": "URI '/v1/chat/completions' is not supported by this model. Supported URIs: ['/v1/responses']", "type": "invalid_request_error", "code": "http_error"}}`
400	Gemini Native called with a non-Gemini model	`{"error": {"code": 400, "message": "URI '/v1beta/models/...:generateContent' is not supported by this model. Supported URIs: ['/v1/chat/completions']", "status": "INVALID_ARGUMENT"}}`
401	Missing or invalid API key	`{"code": 401, "error": {"message": "Invalid API key", "type": "authentication_error"}}`
404	Unknown model id	`{"error": {"message": "Model not found: ...", "type": "invalid_request_error", "code": "model_not_found"}}`

See LLM Models for which API formats each model supports.

Error Handling Best Practices

Implement retry logic: For 500, 502, and 503 errors, implement exponential backoff retry logic.

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: Keep track of your credit balance to avoid 402 errors during critical operations.

Overview

Task Management

File Management

Account Management

Security & Best Practices

Error Codes

Error Codes

Response Format

Success Response

Error Response

Task Failed Response

Business Status Codes

200 - Success

400 - Bad Request

401 - Unauthorized

402 - Payment Required

403 - Forbidden

404 - Not Found

408 - Request Timeout

429 - Too Many Requests

500 - Internal Server Error

502 - Bad Gateway

503 - Service Unavailable

LLM Endpoint Errors

Error Handling Best Practices

​Error Codes

​Response Format

​Success Response

​Error Response

​Task Failed Response

​Business Status Codes

​200 - Success

​400 - Bad Request

​401 - Unauthorized

​402 - Payment Required

​403 - Forbidden

​404 - Not Found

​408 - Request Timeout

​429 - Too Many Requests

​500 - Internal Server Error

​502 - Bad Gateway

​503 - Service Unavailable

​LLM Endpoint Errors

​Error Handling Best Practices

Error Codes

Response Format

Success Response

Error Response

Task Failed Response

Business Status Codes

200 - Success

400 - Bad Request

401 - Unauthorized

402 - Payment Required

403 - Forbidden

404 - Not Found

408 - Request Timeout

429 - Too Many Requests

500 - Internal Server Error

502 - Bad Gateway

503 - Service Unavailable

LLM Endpoint Errors

Error Handling Best Practices