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

# Error Codes

> Common API error codes, what they mean, and how to fix them.

When something goes wrong, the ShuttleAI API returns a JSON error response with an HTTP status code, error message, and error type.

## Error response format

```json theme={null}
{
  "error": {
    "message": "Detailed error description",
    "type": "error_type",
    "code": 400
  }
}
```

## Error codes

### 400 — Bad Request

**Your request is malformed or missing required fields.**

Common causes:

* Missing or empty `messages` array
* Invalid `model` ID
* Malformed JSON body
* Invalid parameter values (e.g., `temperature: 5`)

**Fix:** Check your request body against the [API reference](/api-reference/introduction).

***

### 401 — Unauthorized

**Your API key is missing, invalid, or malformed.**

Common causes:

* No `Authorization` header
* API key doesn't start with `shuttle-`
* Typo in the API key

**Fix:** Double-check your API key. Make sure the header is `Authorization: Bearer shuttle-xxx`.

***

### 402 — Payment Required

**You don't have an active plan.**

Common causes:

* No subscription on your account
* Subscription has expired
* Payment failed

**Fix:** [Subscribe to a plan](https://shuttleai.com/plans) or check your [billing page](https://shuttleai.com/billing) for payment issues.

***

### 403 — Forbidden

**Your plan doesn't include access to the requested model.**

Common causes:

* Trying to use a Premium model on a Basic plan
* Trying to use a Basic model on a Free plan

**Fix:** [Upgrade your plan](https://shuttleai.com/plans) to access higher-tier models, or switch to a model available on your current tier.

***

### 423 — Locked

**Your account has been suspended.**

Common causes:

* Terms of service violation
* Abuse detected

**Fix:** Contact support on [Discord](https://discord.com/invite/shuttleai) for more information.

***

### 429 — Too Many Requests

**You've exceeded your rate limit.**

Common causes:

* Sending more requests per minute than your plan allows
* Not accounting for [request multipliers](/pricing/multipliers)

**Fix:** Wait until the next minute window and retry. Consider upgrading for higher rate limits.

<Tip>
  Implement exponential backoff in your code to handle 429 errors gracefully:

  ```python theme={null}
  import time

  def make_request_with_retry(func, max_retries=3):
      for attempt in range(max_retries):
          try:
              return func()
          except Exception as e:
              if "429" in str(e) and attempt < max_retries - 1:
                  time.sleep(2 ** attempt)  # 1s, 2s, 4s
              else:
                  raise
  ```
</Tip>

***

### 500 — Internal Server Error

**Something went wrong on our end.**

**Fix:** Wait a moment and retry. If the error persists, check [status.shuttleai.com](https://status.shuttleai.com) or report it on [Discord](https://discord.com/invite/shuttleai).

***

### 503 — Service Unavailable

**The requested model or service is temporarily unavailable.**

Common causes:

* Model is undergoing maintenance
* Upstream provider is down
* High demand causing temporary capacity issues

**Fix:** Try a different model, or wait and retry. Check [status.shuttleai.com](https://status.shuttleai.com) for ongoing incidents.

## Best practices

<AccordionGroup>
  <Accordion title="Always handle errors">
    Never assume API calls will succeed. Wrap calls in try/catch and handle each error code appropriately.
  </Accordion>

  <Accordion title="Implement retries with backoff">
    For 429 and 5xx errors, retry with exponential backoff instead of immediately re-sending.
  </Accordion>

  <Accordion title="Log error responses">
    Log the full error response (message + type + code) to make debugging easier.
  </Accordion>

  <Accordion title="Monitor your usage">
    Use the [Dashboard](/dashboard/overview) to understand your usage patterns and avoid hitting rate limits.
  </Accordion>
</AccordionGroup>