# Error Codes

Source: https://staging-docs.aiand.com/errors/

## Error format

All errors follow the OpenAI-compatible error format:

```json
{
  "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

```python
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.