Errors

Error Response Format

All errors return a JSON object with this structure:

type ErrorResponse = {
  error: {
    message: string;
    type: string;
    code?: string;
    metadata?: Record<string, unknown>;
  };
};

The HTTP status code matches the error type. Request validation errors return non-200 status codes. Errors occurring during generation may be returned in the response body or as SSE events (for streaming).

HTTP Status Codes

400 Bad Request

Invalid request parameters, malformed JSON, or missing required fields.

{
  "error": {
    "message": "Invalid request: model is required",
    "type": "invalid_request_error"
  }
}

Common causes:

Missing required fields (model, messages)
Invalid parameter values (e.g., temperature > 2.0)
Malformed JSON
Invalid message format

401 Unauthorized

Invalid, expired, or missing API key.

{
  "error": {
    "message": "Authentication required",
    "type": "authentication_error"
  }
}

402 Payment Required

Insufficient credits or account balance.

{
  "error": {
    "message": "Insufficient credits",
    "type": "insufficient_quota_error"
  }
}

403 Forbidden

Content moderation failure. Input was flagged by safety systems.

{
  "error": {
    "message": "Content flagged by moderation",
    "type": "content_filter_error",
    "metadata": {
      "reasons": ["violence", "harassment"],
      "flagged_input": "...",
      "provider_name": "openai",
      "model_slug": "gpt-5-mini"
    }
  }
}

408 Request Timeout

Request exceeded timeout limit.

{
  "error": {
    "message": "Request timeout",
    "type": "timeout_error"
  }
}

429 Too Many Requests

Rate limit exceeded.

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error"
  }
}

Check rate limits via GET /v1/key. See Limits documentation.

502 Bad Gateway

Model provider error or invalid response.

{
  "error": {
    "message": "Provider error",
    "type": "provider_error",
    "metadata": {
      "provider_name": "openai",
      "raw": {...}
    }
  }
}

503 Service Unavailable

No available provider meets routing requirements.

{
  "error": {
    "message": "No available provider",
    "type": "service_unavailable_error"
  }
}

Error Types

`invalid_request_error`

Request validation failed. Check parameter types and required fields.

`authentication_error`

API key authentication failed. Verify key is valid and active.

`insufficient_quota_error`

Account lacks sufficient credits. Add credits to continue.

`rate_limit_error`

Request rate exceeds limits. Implement exponential backoff.

`content_filter_error`

Input flagged by content moderation. Review input content.

`timeout_error`

Request exceeded timeout. Retry with shorter context or simpler request.

`provider_error`

Model provider returned an error. May be transient - retry request.

`service_unavailable_error`

No providers available matching routing requirements. Adjust provider preferences or retry later.

Error Metadata

Some errors include metadata for debugging:

Moderation Errors

type ModerationErrorMetadata = {
  reasons: string[];        // Flag categories
  flagged_input: string;     // Flagged content
  provider_name: string;     // Provider that flagged
  model_slug: string;        // Model identifier
};

Provider Errors

type ProviderErrorMetadata = {
  provider_name: string;     // Provider identifier
  raw: unknown;              // Raw provider response
};

Error Handling Examples

Python

import requests

try:
  response = requests.post(
    "https://api.anannas.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"model": "openai/gpt-5-mini", "messages": [...]}
  )
  response.raise_for_status()
  data = response.json()
except requests.HTTPError as e:
  if e.response.status_code == 401:
    print("Invalid API key")
  elif e.response.status_code == 402:
    print("Insufficient credits")
  elif e.response.status_code == 429:
    print("Rate limit exceeded - retry after delay")
  else:
    error_data = e.response.json()
    print(f"Error: {error_data['error']['message']}")

TypeScript

try {
  const response = await fetch("https://api.anannas.ai/v1/chat/completions", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "openai/gpt-5-mini",
      messages: [...]
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    switch (response.status) {
      case 401:
        console.error("Invalid API key");
        break;
      case 402:
        console.error("Insufficient credits");
        break;
      case 429:
        console.error("Rate limit exceeded");
        break;
      default:
        console.error(error.error.message);
    }
    return;
  }

  const data = await response.json();
} catch (error) {
  console.error("Request failed:", error);
}

Retry Logic

Implement exponential backoff for transient errors:

import time
import random

def retry_with_backoff(func, max_retries=3):
  for attempt in range(max_retries):
    try:
      return func()
    except requests.HTTPError as e:
      if e.response.status_code in [429, 502, 503]:
        wait = (2 ** attempt) + random.uniform(0, 1)
        time.sleep(wait)
        continue
      raise
  raise Exception("Max retries exceeded")

Streaming Errors

In streaming responses, errors are sent as SSE events:

data: {"error": {"message": "Rate limit exceeded", "type": "rate_limit_error"}}

Parse and handle errors in your SSE event loop.

Best Practices

Check Status Codes: Always verify HTTP status before parsing JSON
Handle 429: Implement exponential backoff for rate limits
Log Metadata: Include error metadata in logs for debugging
User-Friendly Messages: Translate technical errors to user-friendly messages
Retry Transient Errors: Retry 502, 503, and 408 errors
Monitor Credits: Track 402 errors and alert when credits are low

Getting Started

Features

API

Models

Use Cases

Community

Error Response Format

HTTP Status Codes

400 Bad Request

401 Unauthorized

402 Payment Required

403 Forbidden

408 Request Timeout

429 Too Many Requests

502 Bad Gateway

503 Service Unavailable

Error Types

`invalid_request_error`

`authentication_error`

`insufficient_quota_error`

`rate_limit_error`

`content_filter_error`

`timeout_error`

`provider_error`

`service_unavailable_error`

Error Metadata

Moderation Errors

Provider Errors

Error Handling Examples

Python

TypeScript

Retry Logic

Streaming Errors

Best Practices

See Also

​Error Response Format

​HTTP Status Codes

​400 Bad Request

​401 Unauthorized

​402 Payment Required

​403 Forbidden

​408 Request Timeout

​429 Too Many Requests

​502 Bad Gateway

​503 Service Unavailable

​Error Types

​invalid_request_error

​authentication_error

​insufficient_quota_error

​rate_limit_error

​content_filter_error

​timeout_error

​provider_error

​service_unavailable_error

​Error Metadata

​Moderation Errors

​Provider Errors

​Error Handling Examples

​Python

​TypeScript

​Retry Logic

​Streaming Errors

​Best Practices

​See Also

Error Response Format

HTTP Status Codes

400 Bad Request

401 Unauthorized

402 Payment Required

403 Forbidden

408 Request Timeout

429 Too Many Requests

502 Bad Gateway

503 Service Unavailable

Error Types

`invalid_request_error`

`authentication_error`

`insufficient_quota_error`

`rate_limit_error`

`content_filter_error`

`timeout_error`

`provider_error`

`service_unavailable_error`

Error Metadata

Moderation Errors

Provider Errors

Error Handling Examples

Python

TypeScript

Retry Logic

Streaming Errors

Best Practices

See Also