Errors - Upstack Data

The Upstack Data API returns errors as JSON responses with a message field and the appropriate HTTP status code. The one exception is a rejected API key, which returns Message — capitalised.

{
  "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:

{
  "message": "Bad Request",
  "errors": [
    { "message": "name is required", "key": "name", "path": ["name"] }
  ]
}

POST /tr/api/events reports validation differently — it returns error.details, naming the event in your batch that failed. That shape is documented with the endpoint.

Status codes

Status	Meaning
`200`	Success.
`400`	Validation error — see `errors` (or `error.details` on the events API).
`401`	The `x-api-key` or `x-pixel-id` header is missing.
`403`	The key is unknown, revoked, or expired; the pixel is inactive; the key lacks the scope this endpoint needs; or the body `pixelId` doesn’t match the `x-pixel-id` header.
`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.
`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.
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.