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

# Errors

> Error response format, status code reference, and how to handle failures from the Upstack Data API.

The Upstack Data API returns errors as JSON responses with a `message` field and
the appropriate HTTP status code.

```json theme={null}
{
  "message": "API key does not have the dashboards:write scope"
}
```

## Validation errors

`400` responses on validated endpoints also include an `errors` array with
per-field detail:

```json theme={null}
{
  "message": "Bad Request",
  "errors": [
    { "message": "name is required", "key": "name", "path": ["name"] }
  ]
}
```

<Note>
  The server-side events API (`POST /tr/api/events`) returns a richer envelope: the same
  top-level `message`, plus a `requestId` and a structured `error` object with a
  machine-readable `code` and per-event `details`. See **Send server-side events** for the
  full shape.
</Note>

## Status codes

| Status | Meaning                                                                                      |
| ------ | -------------------------------------------------------------------------------------------- |
| `200`  | Success.                                                                                     |
| `400`  | Validation error — see `errors` (or `error.details` on the events API).                      |
| `401`  | Missing/invalid `x-api-key` or `x-pixel-id`, revoked key, or expired key.                    |
| `403`  | Key is valid but doesn't carry the required scope.                                           |
| `404`  | Resource not found (or belongs to another pixel — we return 404 rather than leak existence). |
| `413`  | Request body too large (server-side events API — 128 KB limit).                              |
| `429`  | Too many requests — see [Rate limiting](/api-reference/rate-limiting).                       |
| `500`  | Server error. Retry; if persistent, file a support ticket with the request id.               |

## Handling errors

* Treat `4xx` responses as client errors: fix the request, don't retry it as-is.
  `429` is the exception — retry with backoff as described in
  [Rate limiting](/api-reference/rate-limiting).
* Treat `5xx` responses as transient: retry with exponential backoff. If the
  error persists, file a support ticket with the request id.
* Log the full response body — the `message` (and `requestId` where present) is
  what support needs to trace the request.