Errors - Upstack Data

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

{
  "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"] }
  ]
}

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.

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.
`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.