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

# Common error types

> HTTP statuses, the error body shape, and every error code with its fix.

## Error format

REST API errors return a JSON body with a single `error` object:

```json theme={null}
{
  "error": {
    "message": "Your API key is not linked to an active billing account. Please go to Boson.ai to set up billing and purchase credits.",
    "type": "insufficient_quota",
    "param": null,
    "code": "no_billing_account"
  }
}
```

<ResponseField name="error" type="object">
  `message` (string, human-readable), `type` (string, error category), `param` (string or null, the offending parameter if any), `code` (string or null, machine-readable cause).
</ResponseField>

Handle errors by `type` (the stable category) and use `code` to distinguish causes within it.

## Error types

| Status        | `type`                  | Cause                                                                                                             | Fix                                                                                                                                                      |
| ------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`         | `authentication_error`  | Problem with your API key — missing, malformed, or revoked (`code: "invalid_api_key"`).                           | Check the `Authorization: Bearer` header and the key in your [workspace](https://www.boson.ai/workspace/api-key). See [Authentication](/authentication). |
| `400` / `403` | `invalid_request_error` | Malformed request, or the key lacks access to the requested model.                                                | Fix the request per the `message`; for model access, contact support.                                                                                    |
| `429`         | `rate_limit_error`      | Too many requests — **transient**.                                                                                | Retry with backoff.                                                                                                                                      |
| `429`         | `insufficient_quota`    | Billing refusal — **not transient**; retrying cannot succeed until the account changes. See the code table below. | Resolve in [workspace billing](https://www.boson.ai/workspace/billing/overview), not in code.                                                            |
| `5xx`         | `api_error`             | Something failed on the server side.                                                                              | Retry later; report if persistent.                                                                                                                       |

<Warning>
  Both `rate_limit_error` and `insufficient_quota` arrive as `429` — check `error.type` before retrying. A `rate_limit_error` recovers on its own; an `insufficient_quota` never does.
</Warning>

### `insufficient_quota` codes

| `code`                | Meaning                                                                                                 | Fix                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `no_billing_account`  | The key isn't linked to an active billing account — typically a new account that hasn't claimed credit. | [Claim your free trial credit](/free-trial-credit).                       |
| `insufficient_quota`  | Credits are exhausted.                                                                                  | [Add credits](/account-billing/payment-and-credits).                      |
| `monthly_cap_reached` | Your own [monthly spend cap](/account-billing/usage-and-limits) is reached.                             | Raise or remove the cap; it also resets at the start of each month (UTC). |
| `contract_ended`      | The account's contract has ended.                                                                       | Contact your Boson AI representative.                                     |

## Realtime errors

The Realtime WebSocket signals problems with an [`error` server event](/api-reference/realtime/server-events#error) carrying the same `type` / `code` / `message` / `param` fields. Billing refusals use `type: "insufficient_quota"` and are followed by WebSocket close code `4429`; invalid or expired keys close with code `3000`. See the [close-code table](/api-reference/realtime/overview) for all codes.

## Product-specific request errors

* [Avatar input limits and request errors](/models/higgs-avatar/input-options#input-limits)
* [Realtime session limits](/models/higgs-realtime/guides/connections-and-sessions)