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

# Errors

> How HQ reports failures: the error body shape and the status codes you'll see.

Every failed request returns a standard HTTP status code and a JSON body with a single `error` field describing what went wrong:

```json theme={null}
{ "error": "message is handled, not awaiting_review" }
```

Branch on the **HTTP status**. Treat `error` as a human-readable message for logs and developers, not a stable machine code.

## Status codes

| Status                      | Meaning                                                  | Typical cause                                                                                                                   |
| --------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | Malformed, or not valid for the resource's current state | Missing/invalid field, an unknown enum value, or a wrong-state action (e.g. replying to a message that isn't `awaiting_review`) |
| `401 Unauthorized`          | No valid credential                                      | Missing, malformed, expired, or revoked token                                                                                   |
| `402 Payment Required`      | A plan or credit limit blocks the action                 | Out of credits; the plan's email-inbox limit reached                                                                            |
| `403 Forbidden`             | Authenticated but not allowed                            | The token lacks the required [scope](/api/scopes); not an admin; not a participant of the resource                              |
| `404 Not Found`             | No such resource for this caller                         | Unknown id — or a resource in another workspace                                                                                 |
| `409 Conflict`              | Collides with existing state                             | e.g. an email address already in use                                                                                            |
| `429 Too Many Requests`     | Rate limit exceeded                                      | See [Rate limits](/api/rate-limits)                                                                                             |
| `503 Service Unavailable`   | A dependency isn't configured or available               | e.g. billing not configured                                                                                                     |
| `500 Internal Server Error` | Unexpected server error                                  | Retry; if it persists, contact support                                                                                          |

<Note>For resources outside your workspace HQ returns `404`, not `403`, so the API never reveals whether an id you can't access exists.</Note>