> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modelstack.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error codes and handling for the ModelStack API.

## Error Response Format

When an error occurs, the API returns a JSON object with an `error` field:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/models/supported-models) and use a valid model ID.

### 400 — Missing Model Field

```json theme={null}
{
  "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

```json theme={null}
{
  "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](https://modelstack.cc/dashboard) if needed.

### 402 — Insufficient Balance

```json theme={null}
{
  "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](https://modelstack.cc/dashboard/billing) from your dashboard
* [Upgrade your plan](https://modelstack.cc/pricing) for higher credit limits

### 429 — Rate Limit Exceeded

```json theme={null}
{
  "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](https://modelstack.cc/pricing) for higher limits:

| Plan | Rate Limit |
| - | - |
| Starter | 15 RPM |
| Pro | 40 RPM |
| Max | 60 RPM |

### 500 — Internal Server Error

```json theme={null}
{
  "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](https://modelstack.cc) or contact support.

## Error Handling Best Practices

<AccordionGroup>
  <Accordion title="Implement retry logic with exponential backoff">
    For `429` and `500` errors, retry with increasing delays:

    ```python theme={null}
    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")
    ```
  </Accordion>

  <Accordion title="Handle insufficient balance gracefully">
    Check for `402` errors and notify users to add credits:

    ```python theme={null}
    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.")
    ```
  </Accordion>

  <Accordion title="Validate models before sending requests">
    Use the `/v1/models` endpoint to check if a model is supported before making a chat completion request.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.