Skip to main content

​
Error Response Format

When an error occurs, the API returns a JSON object with an error field: 
{
  "error": {
    "message": "A human-readable error description",
    "type": "error_type",
    "code": 400
  }
}

​
Error Codes

HTTP CodeTypeDescription
400invalid_request_errorThe request body is malformed or missing required fields
401authentication_errorInvalid or missing API key
402insufficient_balanceBoth subscription and lifetime credit balances are zero
404not_foundThe requested resource doesn’t exist
429rate_limit_errorYou’ve exceeded your plan’s rate limit
500internal_errorAn unexpected error occurred on our end

​
Common Errors

​
400 — Invalid Model

Returned when you specify a model that isn’t supported: 
{
  "error": {
    "message": "Unsupported model: \"gpt-5\". Supported models include: claude-3-5-haiku-20241022, claude-3-5-sonnet-20241022, claude-3-7-sonnet-20250219, claude-3-haiku-20240307, claude-haiku-4-5, and more. Please check the documentation for the full list.",
    "type": "invalid_request_error",
    "code": 400
  }
}
Fix: Check the supported models list and use a valid model ID.

​
400 — Missing Model Field

{
  "error": {
    "message": "Model field is required in request body",
    "type": "invalid_request_error",
    "code": 400
  }
}
Fix: Include the model field in your request body.

​
401 — Invalid API Key

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": 401
  }
}
Fix: Check that your API key is correct and starts with sk_. Generate a new key from your dashboard if needed.

​
402 — Insufficient Balance

{
  "error": {
    "message": "Insufficient credit balance. Please add credits or upgrade your plan.",
    "type": "insufficient_balance",
    "code": 402
  }
}
Fix: Your subscription and lifetime credits are both exhausted. Either:

​
429 — Rate Limit Exceeded

{
  "error": {
    "message": "Rate limit exceeded. Please retry after a short delay.",
    "type": "rate_limit_error",
    "code": 429
  }
}
Fix: You’ve exceeded your plan’s requests-per-minute limit. Implement exponential backoff or upgrade your plan for higher limits:
PlanRate Limit
Starter15 RPM
Pro40 RPM
Max60 RPM

​
500 — Internal Server Error

{
  "error": {
    "message": "An internal error occurred. Please try again later.",
    "type": "internal_error",
    "code": 500
  }
}
Fix: This is a server-side issue. Retry the request with exponential backoff. If the problem persists, check the status page or contact support.

​
Error Handling Best Practices

For 429 and 500 errors, retry with increasing delays:
import time
from openai import OpenAI, RateLimitError, APIError

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

def make_request_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="claude-sonnet-4-5",
                messages=messages
            )
        except RateLimitError:
            wait = 2 ** attempt
            time.sleep(wait)
        except APIError as e:
            if e.status_code == 500:
                time.sleep(2 ** attempt)
            else:
                raise
    raise Exception("Max retries exceeded")
Check for 402 errors and notify users to add credits:
try:
    response = client.chat.completions.create(
        model="claude-sonnet-4-5",
        messages=[{"role": "user", "content": "Hello"}]
    )
except Exception as e:
    if "402" in str(e):
        print("Out of credits! Visit your dashboard to add more.")
Use the /v1/models endpoint to check if a model is supported before making a chat completion request.