Error Handling

ScaleLLM returns standard HTTP error codes with detailed error messages.

Error Response Format

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid model specified: gpt-4",
    "code": "model_not_found"
  }
}

Error Codes

Status	Type	Description
400	`invalid_request_error`	Malformed request
401	`authentication_error`	Invalid API key
403	`permission_error`	Key lacks permission
404	`not_found_error`	Model or endpoint not found
429	`rate_limit_error`	Rate limit exceeded
500	`server_error`	Internal server error
503	`service_unavailable`	Provider temporarily unavailable

Common Errors

Invalid API Key (401)

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

Fix: Check your API key starts with sk_ and is active.

Model Not Found (404)

{
  "error": {
    "type": "not_found_error",
    "message": "Model 'gpt-4' not found",
    "code": "model_not_found"
  }
}

Fix: Use a valid model name like claude-sonnet-4.5.

Rate Limit (429)

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

Fix: Wait and retry with exponential backoff.

Handling Errors

Python
JavaScript

from openai import OpenAI, APIError, RateLimitError, AuthenticationError

client = OpenAI(
    base_url="https://api.scalellm.dev/v1",
    api_key="sk_your_key"
)

try:
    response = client.chat.completions.create(
        model="claude-sonnet-4.5",
        messages=[{"role": "user", "content": "Hello"}]
    )
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limited - retry later")
except APIError as e:
    print(f"API error: {e.message}")

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.scalellm.dev/v1',
  apiKey: 'sk_your_key'
});

try {
  const response = await client.chat.completions.create({
    model: 'claude-sonnet-4.5',
    messages: [{ role: 'user', content: 'Hello' }]
  });
} catch (error) {
  if (error.status === 401) {
    console.log('Invalid API key');
  } else if (error.status === 429) {
    console.log('Rate limited - retry later');
  } else {
    console.log(`API error: ${error.message}`);
  }
}

Using Fallbacks

Configure fallback models to handle provider errors automatically:

curl https://api.scalellm.dev/v1/chat/completions \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4.5",
    "messages": [{"role": "user", "content": "Hello"}],
    "fallback_models": ["gemini-3-pro-preview"]
  }'

If Claude is unavailable, ScaleLLM automatically tries Gemini.

Introduction

Setup Guides

Concepts

Billing

Error Handling

Error Handling

Error Response Format

Error Codes

Common Errors

Invalid API Key (401)

Model Not Found (404)

Rate Limit (429)

Handling Errors

Using Fallbacks

Introduction

Setup Guides

Concepts

Billing

​Error Handling

​Error Response Format

​Error Codes

​Common Errors

​Invalid API Key (401)

​Model Not Found (404)

​Rate Limit (429)

​Handling Errors

​Using Fallbacks

Error Handling

Error Response Format

Error Codes

Common Errors

Invalid API Key (401)

Model Not Found (404)

Rate Limit (429)

Handling Errors

Using Fallbacks