UniterRouter API error codes and troubleshooting guide. Handle rate limits, authentication errors, model errors for GPT-4, Claude, Gemini APIs with best practices.

Error Handling

UniterRouter uses standard HTTP response codes and returns errors in a consistent JSON format compatible with OpenAI's API specification.

Error Response Format

All errors follow this structure:

{
  "error": {
    "message": "A human-readable error message",
    "type": "error_type",
    "param": "parameter_name",  // Optional: the parameter that caused the error
    "code": "error_code"
  }
}

HTTP Status Codes

Status Code	Description
`200`	Success
`400`	Bad Request — Invalid request parameters
`401`	Unauthorized — Invalid or missing API key
`402`	Payment Required — Insufficient balance
`403`	Forbidden — Access denied by IAM rules
`404`	Not Found — Model or resource not found
`429`	Too Many Requests — Rate limit exceeded
`500`	Internal Server Error — Server-side error
`502`	Bad Gateway — Upstream provider error
`503`	Service Unavailable — No available channels

Error Types

Authentication Errors

invalid_api_key — The API key is invalid or missing.

{
  "error": {
    "message": "Incorrect API key provided. You can find your API key at https://uniterouter.ai/dashboard.",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Solution: Verify your API key is correct and properly formatted in the Authorization header.

Model Errors

model_not_found — The requested model doesn't exist or isn't accessible.

{
  "error": {
    "message": "The model `gpt-5` does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

Solution: Check the Models page for available models.

Quota & Billing Errors

insufficient_quota — Your account balance is too low.

{
  "error": {
    "message": "You exceeded your current quota, please check your plan and billing details.",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

Solution: Add credits to your account in the Billing Dashboard.

Rate Limit Errors

rate_limit_exceeded — Too many requests in a short period.

{
  "error": {
    "message": "Rate limit reached. Please pace your requests.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

Solution: Implement exponential backoff and reduce request frequency. See Rate Limits.

Service Errors

no_available_channel — No provider channels available for the model.

{
  "error": {
    "message": "No available channel for model `gpt-4o`. Please try again later or contact support.",
    "type": "server_error",
    "code": "no_available_channel"
  }
}

Solution: Retry after a short delay. If persistent, contact support.

no_available_key — All provider API keys are rate limited or disabled.

{
  "error": {
    "message": "No available API keys for model `claude-3-opus`. All keys may be rate limited or disabled.",
    "type": "server_error",
    "code": "no_available_key"
  }
}

Solution: Wait and retry, or consider using BYOK (Bring Your Own Key).

provider_error — Upstream provider returned an error.

{
  "error": {
    "message": "The upstream provider returned an error: context_length_exceeded",
    "type": "server_error",
    "code": "provider_error"
  }
}

Solution: Check if your request exceeds the model's context length or other limits.

service_unavailable — The server is overloaded.

{
  "error": {
    "message": "The server is currently overloaded. Please try again later.",
    "type": "server_error",
    "code": "service_unavailable"
  }
}

Solution: Implement retry logic with exponential backoff.

Handling Errors in Code

Python

from openai import OpenAI, APIError, AuthenticationError, RateLimitError

client = OpenAI(
    base_url="https://api.uniterouter.ai/v1",
    api_key="your_api_key",
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except RateLimitError as e:
    print(f"Rate limited, retrying after backoff: {e}")
except APIError as e:
    print(f"API error: {e.status_code} - {e.message}")

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.uniterouter.ai/v1",
  apiKey: process.env.UNITEROUTER_API_KEY,
});

try {
  const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello!" }],
  });
} catch (error) {
  if (error instanceof OpenAI.AuthenticationError) {
    console.error("Invalid API key");
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("Rate limited, implement backoff");
  } else if (error instanceof OpenAI.APIError) {
    console.error(`API Error: ${error.status} - ${error.message}`);
  }
}

Retry Strategy

For transient errors (429, 503, 502), implement exponential backoff:

import time
import random

def call_with_retry(func, max_retries=5):
    for attempt in range(max_retries):
        try:
            return func()
        except (RateLimitError, ServiceUnavailableError) as e:
            if attempt == max_retries - 1:
                raise
            # Exponential backoff with jitter
            delay = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)

Tip: The OpenAI SDK has built-in retry logic. Configure it with max_retries parameter.

Error Code Reference

Code	HTTP Status	Description
`invalid_api_key`	401	API key is invalid or missing
`invalid_request`	400	Request body is malformed
`model_not_found`	404	Model doesn't exist or no access
`insufficient_quota`	402	Account balance is too low
`rate_limit_exceeded`	429	Too many requests
`no_available_channel`	503	No provider available
`no_available_key`	503	All provider keys exhausted
`provider_error`	502	Upstream provider error
`service_unavailable`	503	Server overloaded
`internal_error`	500	Unexpected server error

Next Steps

Review Rate Limits to avoid hitting limits
Learn about API Key Management
Explore Routing for fallback strategies

Error Handling

On this page