Reference

Errors

Every error returns the same JSON shape and a meaningful status code. We never return 200 with an error body.

Status codes

Code	Meaning	What to do
400	Malformed request — invalid JSON or an unknown query parameter	Fix the request. Retrying will not help.
401	Missing, malformed, or revoked API key	Check the `Authorization` header and that the key is still active.
404	The resource does not exist, or your key cannot see it	Do not distinguish between these two — we deliberately do not.
422	Valid JSON, invalid values — the most common real error	Read `error.fields`; it names each offending field.
429	Rate limit exceeded (120 requests per minute per key)	Wait for `Retry-After` seconds, then retry with jitter.
500	Our fault	Retry once after a short delay. If it persists, the status page will say so before support can.

Error shape

{
  "error": {
    "type": "invalid_request",
    "code": "urgency_overrides_disabled",
    "message": "urgency above 3 requires urgency overrides to be enabled for this clinic",
    "fields": {
      "urgency": "must be 3 or lower for clinic cln_4t7q"
    },
    "request_id": "req_5v2xQ8",
    "docs_url": "https://api.brightloom.dev/docs/errors#urgency_overrides_disabled"
  }
}

Gotchas

Always log request_id. It is the only thing support needs to find your exact request.
code is stable and safe to branch on. message is written for humans and may change.
A 422 never partially applies. Nothing was written.
Retry only on 429 and 500. Retrying a 422 produces the same error and burns rate limit.