Error Handling

This guide covers common API errors and how to handle them properly in your applications.

Error Response Format

All errors follow a consistent JSON format:

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

HTTP Status Codes

Code	Meaning	Solution
400	Bad Request	Check request format and parameters
401	Unauthorized	Verify your API key
402	Payment Required	Top up your account
403	Forbidden	Check API key permissions
404	Not Found	Verify the endpoint URL and model ID
429	Rate Limited	Wait and retry, or check Rate Limits
500	Server Error	Retry after a short delay
502	Bad Gateway	Upstream provider issue, retry
503	Service Unavailable	Temporary outage, retry shortly

Common Errors

401 — Invalid API Key

{"error": {"message": "Invalid API key provided", "type": "authentication_error"}}

Fix:

• Check your API key is correct (no extra spaces)
• Ensure the key is active on the API Keys page
• Use the correct header format: Authorization: Bearer sk-xxx

402 — Insufficient Credits

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

Fix:

• Check your balance in the Console
• Purchase more credits

429 — Rate Limited

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

Fix:

• Implement exponential backoff
• Reduce request frequency
• See Rate Limits

404 — Model Not Found

{"error": {"message": "Model not found: invalid-model", "type": "not_found_error"}}

Fix:

• Check the model ID spelling
• Use the /models endpoint to list available models
• See the Models page

Retry Strategy

Implement exponential backoff for transient errors (429, 500, 502, 503):

import time
from openai import OpenAI, APIError, RateLimitError

client = OpenAI(
    api_key="sk-your-toprouter-key",
    base_url="https://toprouter.cc"
)

def chat_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="google/gemini-3.5-flash",
                messages=messages
            )
        except RateLimitError:
            wait = 2 ** attempt
            print(f"Rate limited. Retrying in {wait}s...")
            time.sleep(wait)
        except APIError as e:
            if e.status_code >= 500:
                wait = 2 ** attempt
                print(f"Server error. Retrying in {wait}s...")
                time.sleep(wait)
            else:
                raise
    raise Exception("Max retries exceeded")

TIP

For production applications, use a library like tenacity (Python) or implement circuit breaker patterns for robust error handling.