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

# Errors

> Structured error envelopes, machine-readable codes, and HTTP status mapping.

Every Public API v1 error returns a consistent JSON envelope:

```json theme={null}
{
  "success": false,
  "code": "TICKET_NOT_FOUND",
  "message": "Ticket not found",
  "request_id": "req_abc123",
  "retry_after": 42
}
```

| Field         | Description                                                      |
| ------------- | ---------------------------------------------------------------- |
| `success`     | Always `false`                                                   |
| `code`        | Machine-readable error code — match on this in integrations      |
| `message`     | Human-readable detail — log only; do not branch logic on wording |
| `request_id`  | Correlation ID for support and log lookup                        |
| `details`     | Optional structured context (validation issues)                  |
| `retry_after` | Present on rate limit errors — seconds to wait                   |

## Error codes

| Code                  | HTTP | When                                                                   |
| --------------------- | ---- | ---------------------------------------------------------------------- |
| `API_KEY_REQUIRED`    | 401  | Missing `cx-api-key` header                                            |
| `INVALID_API_KEY`     | 401  | Key not found or revoked                                               |
| `API_KEY_ORG_MISSING` | 401  | Key has no organization binding                                        |
| `FORBIDDEN_SCOPE`     | 403  | Key lacks required scope for the route                                 |
| `VIEW_NOT_FOUND`      | 404  | Unknown `view_id`, cross-org view, or view not visible to linked agent |
| `TICKET_NOT_FOUND`    | 404  | Ticket number does not exist in the organization                       |
| `INVALID_FILTER`      | 400  | Invalid filter or view configuration                                   |
| `VALIDATION_ERROR`    | 400  | Malformed query params or unknown fields                               |
| `RATE_LIMIT_EXCEEDED` | 429  | Per-route rate limit hit                                               |
| *(none)*              | 500  | Unexpected server error — retry with backoff                           |

## Validation errors

`VALIDATION_ERROR` responses may include a `details` object with field-level issues from Zod validation (for example invalid UUID format on `view_id`).

## Support and debugging

When contacting support, include:

* `request_id` from the error response
* HTTP method and path
* Timestamp (UTC)
* API key name (never the secret value)

## Related

* [Rate limits](/api/rate-limits) — `RATE_LIMIT_EXCEEDED` and `Retry-After`
* [Authentication](/api/authentication) — scope and key errors
* [OpenAPI reference](https://api.armin.cx/docs/v1) — per-endpoint error response schemas