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
`402`	`payment_required`	Insufficient credits — top up your account
`403`	`permission_error` / `forbidden_error`	Key doesn’t have access to the requested provider or resource
`413`	`invalid_request_error`	Request body too large (max 10 MB)
`429`	`rate_limit_error`	Rate limit exceeded (RPM or daily cap)
`502`	`server_error`	Upstream provider request failed
`503`	`server_error`	No available providers for the requested model

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.ai/v1",
    api_key="lr_live_xxxx",
)

try:
    response = client.chat.completions.create(
        model="openai/gpt-5.4",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except APIStatusError as e:
    if e.status_code == 401:
        print("Invalid API key")
    elif e.status_code == 402:
        print("Insufficient credits — top up your account")
    elif e.status_code == 429:
        print("Rate limited, backing off...")
    elif e.status_code in (502, 503):
        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.ai/v1",
  apiKey: "lr_live_xxxx",
});

try {
  const response = await client.chat.completions.create({
    model: "openai/gpt-5.4",
    messages: [{ role: "user", content: "Hello!" }],
  });
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    switch (error.status) {
      case 401: console.error("Invalid API key"); break;
      case 402: console.error("Insufficient credits"); break;
      case 429: console.error("Rate limited"); break;
      case 502:
      case 503: 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 multi-model routing — if one model cannot serve the request, send an ordered candidate list via models and route

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, 503) and attempt < max_retries - 1:
                time.sleep(2 ** attempt)
                continue
            raise

Handling Errors During Streaming

When streaming (stream: true), errors behave differently depending on when they occur:

Before any tokens are sent — ARouter returns a standard HTTP error response with a non-200 status code. Handle this the same as non-streaming errors.
After tokens have been sent — The HTTP status is already 200 OK. The error is delivered as an SSE event in the stream body.

Mid-stream errors look like:

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion.chunk",
  "error": {
    "code": "server_error",
    "message": "Provider disconnected unexpectedly"
  },
  "choices": [
    { "index": 0, "delta": { "content": "" }, "finish_reason": "error" }
  ]
}

Check the finish_reason on each chunk. If it’s "error", the stream has terminated abnormally.

for await (const chunk of stream) {
  // Check for mid-stream error
  if ("error" in chunk) {
    console.error(`Stream error: ${(chunk as any).error.message}`);
    break;
  }
  if (chunk.choices[0]?.finish_reason === "error") {
    console.error("Stream terminated due to an error");
    break;
  }
  const content = chunk.choices[0]?.delta?.content;
  if (content) process.stdout.write(content);
}

See the Streaming Guide for complete error handling examples.

Get Started

Core Concepts

Routing

Features

Guides

Privacy

Administration

Best Practices

Frameworks & Integrations

For Providers

Support

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

Handling Errors During Streaming

​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

​Handling Errors During Streaming

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

Handling Errors During Streaming