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

# API errors and status codes

> Every Omnichar API error has one shape: an error object with a code, a message and a request id, sent with the matching HTTP status. Codes listed here.

Errors share one shape, whatever went wrong:

```json theme={null}
{
  "error": {
    "code": "licensee_not_found",
    "message": "No team or account matches that licensee.",
    "request_id": "9c1e6a2b-..."
  }
}
```

Branch on `code`, not on `message`: messages are written for people and can change. Include `request_id` when you contact us about a failed call. The same id comes back in the `x-request-id` response header, and if you send your own `x-request-id`, it is used instead. Older responses also carry the same value as `requestId`.

| Code | Status | Meaning |
| - | - | - |
| `bad_request` | 400 | The request could not be read. |
| `unauthorized` | 401 | No key, or the key is unknown, revoked or past its rotation window. |
| `forbidden` | 403 | The key lacks the scope, your team lacks the role (for example, issuing licenses), or API access is off for the team. |
| `not_found` | 404 | No such character, license or route in this environment. |
| `licensee_not_found` | 404 | No team matches the licensee id or slug you named. An unknown email is not an error: see [Licenses](https://docs.omnichar.org/api/licenses.md). |
| `conflict` | 409 | The state does not allow it yet: retraining while building, licensing a character that is not ready, a test event from a live key, or an idempotent request still in progress. |
| `unprocessable` | 422 | The body failed validation, or an `Idempotency-Key` was reused with a different body. |
| `storage_limit_reached` | 409 | An upload would take your team over its storage allowance. |
| `rate_limited` | 429 | Too many requests. See [Rate limits](https://docs.omnichar.org/api/rate-limits.md). |
| `insufficient_credits` | 402 | No builds left and not enough credits for a production build. |
| `upstream_unavailable` | 503 | A dependency is down, or a feature is not switched on yet. Try again later. |
| `internal` | 500 | Something failed on our side. |

A `5xx` is safe to retry with the same `Idempotency-Key`; see [Safe retries](https://docs.omnichar.org/api/idempotency.md).

## License checks

A run or download with a [licensed character](https://docs.omnichar.org/api/licensed-characters.md) that the license does not cover answers `403` with the code `forbidden` and the reason in `details`:

```json theme={null}
{
  "error": {
    "code": "forbidden",
    "message": "The license does not allow this territory.",
    "details": { "reason": "territory_not_allowed", "char_id": "7f1c...", "license_key": "lic_live_..." },
    "request_id": "..."
  }
}
```

| `details.reason` | When |
| - | - |
| `no_license` | Your team has no license for this character in this environment. |
| `license_pending` | The license's `starts_at` is still ahead. |
| `license_revoked` | The provider revoked the license. |
| `license_expired` | `ends_at` has passed. |
| `signature_invalid` | The license on record does not match its signature. Contact us. |
| `media_not_allowed` | The run makes an output type that is not in `scope.media`. |
| `use_not_allowed` | `license_context.use` is not the license's `scope.use`. |
| `territory_not_allowed` | `license_context.territory` is not in `scope.territories`. |
| `surface_not_allowed` | `scope.allow_list` names other surfaces or other teams. |
| `limit_reached` | The license has used all of `scope.max_generations`. |

A blocked run never holds or charges credits. A run that was accepted and then blocked when it left the queue, because the license changed while it waited, fails with the same reason and is not charged either. A run with a licensed character and no `license_context` answers `400` with the code `bad_request`.


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