Errors

The API uses standard HTTP status codes. The body always contains an error object with message and type.

Error format

All errors return the same format:

json

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

error.message— Human-readable error description.

error.type— Error type code for programmatic handling.

error.code— Corresponding HTTP status code.

400bad_request

The request body is malformed or missing required fields.

Fix: Check that model and messages are present and correctly formatted.

401authentication_error

The API key is missing, invalid, or has been revoked.

Fix: Verify your key at /token. Generate a new one if needed.

403permission_error

Your account does not have access to this model or feature.

Fix: Check your plan limits or contact support.

404not_found

The requested model or endpoint does not exist.

Fix: Check the model ID at /docs/models.

408timeout

The request took too long to process.

Fix: Try a shorter prompt or a faster model.

429rate_limit_error

You have exceeded the rate limit for your plan.

Fix: Wait before retrying. Consider upgrading your plan for higher limits.

500server_error

An unexpected error occurred on the server.

Fix: Retry the request. If it persists, contact support.

503model_unavailable

The requested model is temporarily unavailable.

Fix: Try another model or wait and retry.

Always check the HTTP status code before processing the response.

Implement exponential backoff for 429 and 5xx errors.

For model unavailable errors (503), implement fallback to another model.