Getting started

Errors

The same shape every time. Write your if on error.code — it is stable.

Errors always have the same shape. Write your if on error.code — it is stable. The text in message is for the person debugging and may be reworded.

JSON

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key is missing the \"services:write\" scope."
  }
}

The codes

Code	Status	What it means	What you do
`invalid_request`	400	A field is missing, too long, or the wrong type.	Read `error.message` — it names the field.
`unauthorized`	401	No key, an unknown key, or a revoked one.	Check the Authorization header. A copied key often carries a trailing space — we trim it, but a truncated key we cannot fix.
`insufficient_scope`	403	The key is valid but lacks the scope this endpoint needs.	The message names the missing scope. Tick it on the key, or create a new one.
`account_suspended`	403	The key is valid — the account is closed. Either suspended or cancelled.	A new key will not help; the key is not the problem. Write to us and we will say why, and what it takes.
`not_found`	404	No row with that id — in your organisation.	We never say whether the id exists somewhere else. Check the id against a list call.
`conflict`	409	The request was valid, but reality said no — the slot is taken, or the practitioner is not available.	Fetch the state again and show the customer what is actually free.
`rate_limited`	429	Too many calls this minute.	Wait for `X-RateLimit-Reset`. See Rate limits & paging.
`route_not_configured`	500	Our mistake: an endpoint without a scope mapping.	Write to us — it has to be fixed on our side, not yours.
`server_error`	500	Something broke on our side.	Retry with a growing pause. If it persists, write to us.

Three different 403s. insufficient_scope and account_suspended look the same in
the status code but need different actions — one you fix yourself on the key, the other
only we can resolve.