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

# Errors

> Troubleshoot API failures with the error envelope and stable error codes.

Every error from the Chief Public API uses the same JSON envelope:

```json theme={null}
{
  "code": "publicapi.auth.invalid",
  "humane": "The provided API key is invalid or has been revoked.",
  "statusCode": 401
}
```

| Field        | Description                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------- |
| `code`       | Stable, dotted, lowercase identifier (`domain.operation.reason`). Use for i18n keys and analytics. |
| `humane`     | Plain English safe to show end users.                                                              |
| `statusCode` | Mirrors the HTTP status code.                                                                      |

`code` values are additive. Existing codes are never reworded.

## HTTP status reference

| Status | Meaning                                                           |
| ------ | ----------------------------------------------------------------- |
| `400`  | Malformed request, validation failure, or missing tenancy header. |
| `401`  | Authentication failure.                                           |
| `404`  | Resource does not exist or is outside the caller's reach.         |
| `500`  | Unexpected server error.                                          |

## Documented error codes

| Code                                | HTTP | When                                    |
| ----------------------------------- | ---- | --------------------------------------- |
| `publicapi.auth.invalid`            | 401  | PAT is missing, malformed, or revoked.  |
| `publicapi.tenancy.project.missing` | 400  | `X-Project-Id` is missing or malformed. |

<Note>
  Additional operation-specific codes may appear in v1. Prefer HTTP status for broad handling and `code` when you need precise branching.
</Note>

## Validation errors

Invalid JSON bodies, unknown fields, or id shape mismatches typically return HTTP `400`. Resource ids use fixed prefixes and lengths:

| Prefix     | Example                        |
| ---------- | ------------------------------ |
| `chat_`    | `chat_d8aad64dib2c7m3ae7j0`    |
| `message_` | `message_d8aad64dib2c7m3ae7jg` |
| `asset_`   | `asset_d8aad64dib2c7m3ae7j1`   |
| `label_`   | `label_d8aad64dib2c7m3ae7k0`   |
| `project_` | `project_d8a4td4dib27i4beefb0` |

## Client recommendations

* Log `code` and HTTP status for support and metrics.
* Show `humane` to users when appropriate; do not parse it for control flow.
* Retry `5xx` with exponential backoff.
* Do not retry `4xx` unless you fix the request (for example, add a valid `X-Project-Id`).

## Pagination errors

| Situation                           | Typical response |
| ----------------------------------- | ---------------- |
| Both `after_id` and `before_id` set | HTTP `400`       |
| `limit` outside 1–100               | HTTP `400`       |

See [Pagination](/api-reference/pagination) for valid query parameters.