Skip to main content
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"
  }
}
FieldDescription
messageHuman-readable description of the error
typeError category (e.g., api_error, validation_error)
codeMachine-readable error code
reference_idUnique ID for support inquiries
timestampWhen the error occurred

​
HTTP Status Codes

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

​
Common Error Codes

​
Authentication Errors

CodeDescription
MISSING_HEADERNo Authorization header provided
INVALID_FORMATAuthorization header format is incorrect
INVALID_KEYAPI key is invalid or doesn’t exist
INVALID_OAUTH_TOKENOAuth token is invalid
ACCOUNT_DISABLEDUser account has been disabled
IP_ACCESS_DENIEDRequest IP not in allowlist

​
Request Errors

CodeDescription
INVALID_MODELRequested model doesn’t exist
INSUFFICIENT_CREDITSNot enough credits for this request
RATE_LIMIT_EXCEEDEDToo many requests
VALIDATION_ERRORRequest body validation failed

​
Provider Errors

CodeDescription
PROVIDER_ERRORUpstream provider returned an error
PROVIDER_UNAVAILABLEProvider is temporarily unavailable
MODEL_UNAVAILABLESpecific 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

Every error includes a reference_id. Save this for support inquiries - it helps us track down issues quickly.
Most authentication errors are caused by typos or using the wrong API key. Double-check your key starts with sk-voidai-.
Use the Models endpoint to see available models before making requests.
Insufficient credits will cause requests to fail. Check your dashboard for your current balance.

​
Getting Help

If you encounter persistent errors:
  1. Note the reference_id from the error response
  2. Check your dashboard for account status
  3. Join our Discord for community support