> For the complete documentation index, see [llms.txt](https://eventx-hq.gitbook.io/knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://eventx-hq.gitbook.io/knowledge-base/api-v2/error-response-envelope.md).

# Error Response Envelope

All errors return a consistent JSON envelope:

```json
{ "code": "ERR_PUBLIC_API_<NAME>", "message": "Human-readable error", "status": 400, "meta": { "errors": {} } }
```

The `meta` field is optional and contains additional context (e.g., validation field errors).

#### Error Codes

| Code                                       | HTTP Status | Meaning                                                                |
| ------------------------------------------ | ----------- | ---------------------------------------------------------------------- |
| `ERR_PUBLIC_API_VALIDATION_ERROR`          | 400         | Request body or path parameters failed validation                      |
| `ERR_PUBLIC_API_INVALID_STATUS_TRANSITION` | 400         | The requested addon status transition is not allowed                   |
| `ERR_PUBLIC_API_UNAUTHORIZED`              | 401         | Missing, invalid, or revoked JWT                                       |
| `ERR_PUBLIC_API_FORBIDDEN`                 | 403         | User is not authorized for this event (not an organiser or org member) |
| `ERR_PUBLIC_API_NOT_FOUND`                 | 404         | Resource not found within the given scope                              |
| `ERR_PUBLIC_API_PAYLOAD_TOO_LARGE`         | 413         | Request body exceeds the 1MB limit                                     |
| `ERR_PUBLIC_API_RATE_LIMITED`              | 429         | Rate limit exceeded (see Rate Limiting below)                          |
| `ERR_PUBLIC_API_QUOTA_EXCEEDED`            | 429         | Monthly API quota exceeded (100/mo default, per subscription)          |
| `ERR_PUBLIC_API_INTERNAL_ERROR`            | 500         | Unexpected server error                                                |