Error Handling

Error Format

All errors follow a consistent JSON format:

{
  "error": {
    "message": "Human-readable error description",
    "type": "error_type"
  }
}

Error Types

HTTP Status	Error Type	Description
`400`	`invalid_request_error`	Malformed request body or missing required fields
`401`	`authentication_error`	Missing, invalid, or expired API key
`403`	`permission_error` / `forbidden_error`	Key doesn’t have access to the requested provider or resource
`429`	`rate_limit_error`	Rate limit exceeded (RPM or daily cap)
`502`	`server_error`	Upstream provider request failed
`503`	`server_error`	Authentication service temporarily unavailable

Common Errors and Solutions

401 — Invalid API Key

{
  "error": {
    "message": "invalid api key",
    "type": "authentication_error"
  }
}

Fix: Check that your API key is correct and hasn’t been revoked.

403 — Provider Not Allowed

{
  "error": {
    "message": "provider 'anthropic' is not allowed for this API key",
    "type": "forbidden_error"
  }
}

Fix: Your API key has an allowed_providers restriction. Use a different key or update the allowed providers via the management API.

429 — Rate Limited

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

Fix: Implement exponential backoff. Consider raising your key’s rate limit.

502 — Upstream Failed

{
  "error": {
    "message": "upstream request failed",
    "type": "server_error"
  }
}

Fix: The LLM provider returned an error or is unreachable. ARouter automatically handles key failover, but the provider itself may be experiencing issues. Retry or switch to a different provider.

Handling Errors in Code

Python (OpenAI)
Node.js (OpenAI)
Go

from openai import OpenAI, APIStatusError, APIConnectionError

client = OpenAI(
    base_url="https://api.arouter.com/v1",
    api_key="lr_live_xxxx",
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except APIStatusError as e:
    if e.status_code == 401:
        print("Invalid API key")
    elif e.status_code == 429:
        print("Rate limited, backing off...")
    elif e.status_code == 502:
        print("Provider error, retrying...")
    else:
        print(f"API error {e.status_code}: {e.message}")
except APIConnectionError:
    print("Network error — check your connection")

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.arouter.com/v1",
  apiKey: "lr_live_xxxx",
});

try {
  const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello!" }],
  });
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    switch (error.status) {
      case 401: console.error("Invalid API key"); break;
      case 429: console.error("Rate limited"); break;
      case 502: console.error("Provider error"); break;
      default:  console.error(`Error ${error.status}: ${error.message}`);
    }
  }
}

resp, err := client.ChatCompletion(ctx, req)
if err != nil {
    var apiErr *arouter.APIError
    if errors.As(err, &apiErr) {
        switch apiErr.StatusCode {
        case 401:
            log.Fatal("Invalid API key")
        case 429:
            log.Println("Rate limited, backing off...")
            time.Sleep(time.Second)
        case 502:
            log.Println("Provider error, retrying...")
        }
    } else {
        log.Fatal("Network error:", err)
    }
}

Retry Strategy

For production applications, we recommend:

Retry on 429 and 502 with exponential backoff
Do not retry on 400, 401, 403 — these are permanent errors
Set a max retry count (e.g., 3 attempts)
Consider provider fallback — if one provider fails, try another via the provider/model format

import time
from openai import OpenAI, APIStatusError

def call_with_retry(client, request, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**request)
        except APIStatusError as e:
            if e.status_code in (429, 502) and attempt < max_retries - 1:
                time.sleep(2 ** attempt)
                continue
            raise

Get Started

Core Concepts

SDKs

Guides

Error Format

Error Types

Common Errors and Solutions

401 — Invalid API Key

403 — Provider Not Allowed

429 — Rate Limited

502 — Upstream Failed

Handling Errors in Code

Retry Strategy

Get Started

Core Concepts

SDKs

Guides

​Error Format

​Error Types

​Common Errors and Solutions

​401 — Invalid API Key

​403 — Provider Not Allowed

​429 — Rate Limited

​502 — Upstream Failed

​Handling Errors in Code

​Retry Strategy

Error Format

Error Types

Common Errors and Solutions

401 — Invalid API Key

403 — Provider Not Allowed

429 — Rate Limited

502 — Upstream Failed

Handling Errors in Code

Retry Strategy