Errors

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 Code	Type	Description
`400`	`invalid_request_error`	The request body is malformed or missing required fields
`401`	`authentication_error`	Invalid or missing API key
`402`	`insufficient_balance`	Both subscription and lifetime credit balances are zero
`404`	`not_found`	The requested resource doesn’t exist
`429`	`rate_limit_error`	You’ve exceeded your plan’s rate limit
`500`	`internal_error`	An 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:

Wait for your next subscription credit refill (scheduled every 5 hours)
Purchase lifetime credits from your dashboard
Upgrade your plan for higher credit limits

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:

Plan	Rate Limit
Starter	15 RPM
Pro	40 RPM
Max	60 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

Implement retry logic with exponential backoff

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")

Handle insufficient balance gracefully

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.")

Validate models before sending requests

Use the /v1/models endpoint to check if a model is supported before making a chat completion request.

Overview

Endpoints

Error Response Format

Error Codes

Common Errors

400 — Invalid Model

400 — Missing Model Field

401 — Invalid API Key

402 — Insufficient Balance

429 — Rate Limit Exceeded

500 — Internal Server Error

Error Handling Best Practices

​Error Response Format

​Error Codes

​Common Errors

​400 — Invalid Model

​400 — Missing Model Field

​401 — Invalid API Key

​402 — Insufficient Balance

​429 — Rate Limit Exceeded

​500 — Internal Server Error

​Error Handling Best Practices

Error Response Format

Error Codes

Common Errors

400 — Invalid Model

400 — Missing Model Field

401 — Invalid API Key

402 — Insufficient Balance

429 — Rate Limit Exceeded

500 — Internal Server Error

Error Handling Best Practices