Error Codes

Error format

All errors follow the OpenAI-compatible error format:

{
  "error": {
    "message": "A human-readable description of the error",
    "type": "error_type",
    "param": "field_name",
    "code": "error_code"
  }
}

The param and code fields are optional and may be null.

Status codes

Status	Type	Description
400	invalid_request_error	Request validation failed — malformed JSON, missing required fields, or invalid parameter values.
401	authentication_error	Missing or invalid API key / JWT token.
402	insufficient_credits	Billing account balance is too low to process the request. Add credits to continue.
403	permission_error	Valid credentials but insufficient permissions for the requested resource.
404	invalid_request_error	Resource not found — unknown route, or referenced resource (e.g. file_id) doesn’t exist or belongs to a different organization.
410	invalid_request_error	Resource gone — typically a referenced file is past its expires_at.
429	rate_limit_error	Rate limit exceeded. Retry after the cooldown period.
500	internal_error	Unexpected error while serving the request.
502	bad_gateway	Failed to reach the model inference layer.
504	gateway_timeout	Model did not respond within the 30-second timeout.

Common error codes

The code field gives a more specific reason than the type alone. Notable ones:

Code	Status	When
invalid_value	400	A request field has an invalid value (mime type, purpose, etc.)
context_length_exceeded	400	Request exceeds the model’s max context window
model_capability_mismatch	400	Request includes an image_url / video_url / file_id that requires a capability the chosen model lacks
file_not_found	404	Referenced file_id doesn’t exist or isn’t owned by your organization
file_expired	410	Referenced file_id is past its expires_at
invalid_api_key	401	Missing, malformed, or unknown API key
rate_limit_exceeded	429	Per-minute or per-day request/token cap hit
insufficient_credits	402	Balance too low

Handling errors

from openai import OpenAI, APIError

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.aiand.com/v1",
)

try:
    response = client.chat.completions.create(
        model="openai/gpt-oss-120b",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except APIError as e:
    print(f"Status: {e.status_code}")
    print(f"Message: {e.message}")

The OpenAI SDK automatically parses the error response and raises typed exceptions. For 429 errors, implement exponential backoff with retries.