Errors

Every error has one shape. Branch on type and code; show message to developers only.

The envelope#

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "limit must be a whole number from 1 to 100.",
    "param": "limit",
    "request_id": "GON6k_hAgBsHUEMAAGhx"
  }
}

Field	Meaning
`type`	The class of problem. One of six, below. Treat an unknown type as `api_error`.
`code`	The specific problem. Stable once published.
`message`	For the developer. Wording may change, and follows the region's spelling. Never parse it.
`param`	The parameter or header at fault, or `null`. For `wrong_region`, the base URL to use instead.
`request_id`	Also in the `x-request-id` header. Quote it when you contact us.

Types and codes#

Status	`type`	`code`	What to do
401	`authentication_error`	`invalid_credential`	The key or token is missing, wrong, revoked or rotated. Get a new one.
401	`authentication_error`	`api_key_wrong_mode`	A test key on a live clinic, or a live key on the sandbox.
401	`authentication_error`	`machine_credential_required`	A signed-in session was sent. Use a key or OAuth token.
403	`permission_error`	`insufficient_scope`	Ask the clinic for a credential with the scope.
403	`permission_error`	`route_not_allowed`	This endpoint is not open to credentials.
403	`permission_error`	`no_clinic_access`	The credential reaches no clinic, for example after its person left.
403	`permission_error`	`patients_not_visible`	The person the credential acts as cannot see all the clinic's patients.
400	`invalid_request_error`	`parameter_invalid`	Fix the parameter named in `param`.
400	`invalid_request_error`	`parameter_unsupported`	This list does not take that parameter, such as `updated_since` on clinics.
400	`invalid_request_error`	`clinic_required`	Send `Claro-Clinic`. See Choosing a clinic.
400	`invalid_request_error`	`parameter_missing`	Send the required parameter named in `param`, such as `subscription` on `GET /events`.
400	`invalid_request_error`	`event_type_not_subscribed`	A `type` on `GET /events` that the subscription does not take.
400	`invalid_request_error`	`idempotency_key_invalid`	The key must be 1 to 255 characters.
404	`invalid_request_error`	`resource_missing`	No such object, or not one this credential reaches.
404	`invalid_request_error`	`route_not_found`	No such endpoint, whatever the method. Check the path against the reference.
405	`invalid_request_error`	`method_not_allowed`	The path exists, but not with this method. The `Allow` header lists the ones it takes.
421	`invalid_request_error`	`wrong_region`	The API key belongs to the other region. `param` is the base URL to use. See Regions.
409	`idempotency_error`	`idempotency_key_reused`	The key was used for a different request. Use a new key.
409	`idempotency_error`	`idempotency_key_in_progress`	The first request is still running. Retry after `Retry-After`.
429	`rate_limit_error`	`rate_limited`	Wait `Retry-After` seconds. See Rate limits.
500	`api_error`	varies	Our problem. Retry with backoff, and quote `request_id` if it persists.

New codes can be added within a type. Handle an unknown code by its type.

Not found means not yours, too#

A record at a clinic your credential does not reach is a 404, exactly like one that does not exist. The API never confirms that someone else's record exists.

Retrying#

Retry 429, 409 idempotency_key_in_progress and 5xx, with exponential backoff and jitter.
Do not retry other 4xx errors unchanged. They fail the same way again.
When writes arrive, retry a POST with the same Idempotency-Key.