Error Handling

API error codes, descriptions, and recommended handling strategies.

Error Response Format

All errors return a consistent JSON structure:

{
  "error": {
    "message": "Human-readable error description",
    "type": "error_type",
    "param": "parameter_name (if applicable)",
    "code": "error_code"
  }
}

HTTP Status Codes

200Success

Request completed successfully.

400Bad Request

Invalid request body or parameters.

401Unauthorized

Invalid or missing API key.

403Forbidden

API key doesn't have permission for this resource.

404Not Found

Requested resource doesn't exist.

429Rate Limited

Too many requests. Check Retry-After header.

500Internal Error

Server error. Retry with exponential backoff.

503Service Unavailable

Service temporarily unavailable. Retry later.

Error Types

Type	Description
`auth_error`	Authentication failed
`invalid_request_error`	Invalid request parameters
`rate_limit_error`	Rate limit exceeded
`model_error`	Model-related issues
`budget_exceeded`	API key budget limit reached
`api_error`	Internal server error

Handling Examples

Python

from openai import OpenAI, APIError, RateLimitError, AuthenticationError
import time

client = OpenAI(
    base_url="https://altllm-api.viber.autonome.fun/v1",
    api_key="YOUR_API_KEY"
)

def chat_with_retry(message, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="altllm-standard",
                messages=[{"role": "user", "content": message}]
            )
            return response.choices[0].message.content

        except AuthenticationError:
            print("Invalid API key")
            raise

        except RateLimitError as e:
            if attempt < max_retries - 1:
                wait_time = getattr(e, 'retry_after', 60)
                print(f"Rate limited. Waiting {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise

        except APIError as e:
            if attempt < max_retries - 1 and e.status_code >= 500:
                wait_time = 2 ** attempt
                print(f"Server error. Retrying in {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise

TypeScript

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://altllm-api.viber.autonome.fun/v1',
  apiKey: 'YOUR_API_KEY'
});

async function chatWithRetry(message: string, maxRetries = 3): Promise<string> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await client.chat.completions.create({
        model: 'altllm-standard',
        messages: [{ role: 'user', content: message }]
      });
      return response.choices[0].message.content || '';

    } catch (error) {
      if (error instanceof OpenAI.AuthenticationError) {
        console.error('Invalid API key');
        throw error;
      }

      if (error instanceof OpenAI.RateLimitError) {
        if (attempt < maxRetries - 1) {
          const waitTime = 60;
          console.log(`Rate limited. Waiting ${waitTime}s...`);
          await new Promise(r => setTimeout(r, waitTime * 1000));
          continue;
        }
      }

      if (error instanceof OpenAI.APIError && error.status >= 500) {
        if (attempt < maxRetries - 1) {
          const waitTime = Math.pow(2, attempt);
          console.log(`Server error. Retrying in ${waitTime}s...`);
          await new Promise(r => setTimeout(r, waitTime * 1000));
          continue;
        }
      }

      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

Best Practices

Use exponential backoff for 5xx errors
Check Retry-After header for rate limits
Log error details for debugging
Set reasonable timeouts (30-60s for completions)
Handle network errors separately from API errors
Monitor usage to avoid budget exhaustion