Error Handling

VoidAI returns errors in a consistent JSON format. Understanding these errors helps you build robust applications.

Error Response Format

All errors follow this structure:

{
  "error": {
    "message": "Human-readable error description",
    "type": "api_error",
    "code": "ERROR_CODE",
    "reference_id": "req_1701691200_abc123",
    "timestamp": "2024-12-04T12:00:00.000Z"
  }
}

Field	Description
`message`	Human-readable description of the error
`type`	Error category (e.g., `api_error`, `validation_error`)
`code`	Machine-readable error code
`reference_id`	Unique ID for support inquiries
`timestamp`	When the error occurred

HTTP Status Codes

Status	Description
`400`	Bad Request - Invalid parameters or malformed request
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Access denied (IP restrictions, disabled account)
`404`	Not Found - Resource doesn’t exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong on our end
`503`	Service Unavailable - Temporary outage

Common Error Codes

Authentication Errors

Code	Description
`MISSING_HEADER`	No Authorization header provided
`INVALID_FORMAT`	Authorization header format is incorrect
`INVALID_KEY`	API key is invalid or doesn’t exist
`INVALID_OAUTH_TOKEN`	OAuth token is invalid
`ACCOUNT_DISABLED`	User account has been disabled
`IP_ACCESS_DENIED`	Request IP not in allowlist

Request Errors

Code	Description
`INVALID_MODEL`	Requested model doesn’t exist
`INSUFFICIENT_CREDITS`	Not enough credits for this request
`RATE_LIMIT_EXCEEDED`	Too many requests
`VALIDATION_ERROR`	Request body validation failed

Provider Errors

Code	Description
`PROVIDER_ERROR`	Upstream provider returned an error
`PROVIDER_UNAVAILABLE`	Provider is temporarily unavailable
`MODEL_UNAVAILABLE`	Specific model is unavailable

Handling Errors

Python

from openai import OpenAI, APIError, AuthenticationError, RateLimitError

client = OpenAI(
    api_key="sk-voidai-your_key_here",
    base_url="https://api.voidai.app/v1"
)

try:
    response = client.chat.completions.create(
        model="gpt-5.1",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
    # Check your API key
except RateLimitError as e:
    print(f"Rate limit hit: {e.message}")
    # Implement exponential backoff
except APIError as e:
    print(f"API error: {e.message}")
    print(f"Reference ID: {e.body.get('error', {}).get('reference_id')}")
    # Log the reference_id for support

TypeScript

import OpenAI, { APIError, AuthenticationError, RateLimitError } from 'openai';

const client = new OpenAI({
  apiKey: 'sk-voidai-your_key_here',
  baseURL: 'https://api.voidai.app/v1'
});

try {
  const response = await client.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Hello!' }]
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log(`Authentication failed: ${error.message}`);
    // Check your API key
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limit hit: ${error.message}`);
    // Implement exponential backoff
  } else if (error instanceof APIError) {
    console.log(`API error: ${error.message}`);
    // Log for debugging
  }
}

Retry Strategy

For transient errors (5xx, rate limits), implement exponential backoff:

import time
from openai import OpenAI, RateLimitError, APIError

def make_request_with_retry(client, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-4",
                messages=[{"role": "user", "content": "Hello!"}]
            )
        except RateLimitError:
            if attempt < max_retries - 1:
                wait_time = (2 ** attempt) + 1  # 1, 3, 5 seconds
                print(f"Rate limited. Waiting {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise
        except APIError as e:
            if e.status_code >= 500 and attempt < max_retries - 1:
                wait_time = (2 ** attempt) + 1
                print(f"Server error. Waiting {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise

Debugging Tips

Save the reference_id

Every error includes a reference_id. Save this for support inquiries - it helps us track down issues quickly.

Check your API key

Most authentication errors are caused by typos or using the wrong API key. Double-check your key starts with sk-voidai-.

Verify the model exists

Use the Models endpoint to see available models before making requests.

Check your credit balance

Insufficient credits will cause requests to fail. Check your dashboard for your current balance.

Getting Help

If you encounter persistent errors:

Note the reference_id from the error response
Check your dashboard for account status
Join our Discord for community support

Getting Started

Guides

Error Handling

Error Response Format

HTTP Status Codes

Common Error Codes

Authentication Errors

Request Errors

Provider Errors

Handling Errors

Python

TypeScript

Retry Strategy

Debugging Tips

Getting Help

​Error Response Format

​HTTP Status Codes

​Common Error Codes

​Authentication Errors

​Request Errors

​Provider Errors

​Handling Errors

​Python

​TypeScript

​Retry Strategy

​Debugging Tips

​Getting Help

Error Response Format

HTTP Status Codes

Common Error Codes

Authentication Errors

Request Errors

Provider Errors

Handling Errors

Python

TypeScript

Retry Strategy

Debugging Tips

Getting Help