Errors & rate limits

Every error response carries the same JSON envelope, the HTTP status code matches the semantics, and the error string is stable enough to switch on. The list below is exhaustive — if you hit something not on it, please report it to support@tracepass.eu.

Envelope

{
  "error": "Validation error",
  "details": {
    "fieldErrors": {
      "model": ["Required"]
    }
  }
}

error is always present and is a stable string — switch on it in your client. details is optional; when present its shape depends on the specific error (a flattened Zod result for validation, plan/usage numbers for an overage, role / permission name for a 403).

Status codes

Retry guidance

For the “Yes” rows above: exponential backoff with jitter, capped at six attempts. We don't accept retries more aggressive than once-per-second on a single endpoint — anything faster won't hit the database (in-memory rate limiter rejects), but you'll burn your daily-write budget. TheRetry-After header is set on every 503; the rate-limit reset for 429 is always the next 00:00 UTC.

Common error strings