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	billing_error	Billing account balance is too low to process the request. Add credits to continue.
403	authorization_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. How to retry depends on the bucket — see Rate Limits.
499	client_closed_request	Client disconnected before the response finished. Returned for aborted streams.
500	server_error	Unexpected error while serving the request.
502	server_error	Failed to reach the model inference layer.
504	server_error	Model did not respond before the request timeout.

500, 502 and 504 all carry type: "server_error" — read code to tell them apart. A 500 carries no code.

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 — a bad mime type or purpose, or an image_url / video_url / file_id needing a capability the chosen model lacks. param names the field
context_length_exceeded	400	Request exceeds the model’s max context window
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
upstream_error	502	Could not reach the model inference layer, or its response was unreadable
timeout	504	Model did not respond before the request timeout
client_closed_request	499	Client disconnected before the response finished

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, check the X-RateLimit-Policy header and handle the reject by bucket: back off (honoring Retry-After) on time-based rejects, but for concurrency rejects let in-flight requests drain instead of retrying. See Rate Limits.