Guides

Errors

The one error envelope every /public/v1 operation uses, the stable error codes to branch on, and the status codes the OpenAPI document declares.

The error envelope

Every error response from /public/v1 has the same body:

JSON

{ "code": "VALIDATION_ERROR", "message": "The request has invalid fields", "details": { "fields": { "venue_id": ["Invalid uuid"] } } }

Branch on code, never on message. The common codes:

Status	`code`	Meaning
400	`IDEMPOTENCY_KEY_REQUIRED`, `INVALID_CURSOR`	A `POST` without an `Idempotency-Key`, or a cursor that did not come from `next_cursor`
401	`INVALID_TOKEN`	Missing, invalid or expired token, or the client was revoked
403	`INSUFFICIENT_SCOPE`	The token lacks the scope this operation needs
403	`CONSENT_REQUIRED`	The member has not given the consent this data needs (Consent)
404	`NOT_FOUND`	No such record in this clinic group
409	`IDEMPOTENCY_IN_PROGRESS`, or a resource-specific conflict	Retry later, or see the operation's description
422	`VALIDATION_ERROR`, `IDEMPOTENCY_KEY_REUSED`	The request is invalid; `details.fields` names the fields
429	`RATE_LIMITED`	Wait `Retry-After` seconds
500	`INTERNAL_ERROR`	Retry with back-off; contact us if it persists

Fields of the envelope

The Error schema in the OpenAPI document is the body of every non-2xx response from /public/v1.

Error schema
Field	Type	Description
`code`required	`string`	Stable machine-readable error code, e.g. VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_SCOPE.
`message`required	`string`	Human-readable explanation; may change, do not parse.
`details`	`any`	Code-specific detail. VALIDATION_ERROR: `{ fields: { <field>: [messages] } }`.

ExampleJSON

{
  "code": "QS1792807209",
  "message": "The request has invalid fields",
  "details": "string"
}

Status codes in the OpenAPI document

Each operation lists the statuses it can answer; these are all of them. Resource-specific conflicts (for example a voucher that is already redeemed) are described on the operation.

Status	Meaning
400	Malformed request or invalid cursor.
400	Malformed request, invalid cursor, or missing Idempotency-Key (IDEMPOTENCY_KEY_REQUIRED).
401	Missing, invalid or expired access token, or the API client was revoked (INVALID_TOKEN).
403	The token lacks the scope this operation needs (INSUFFICIENT_SCOPE).
404	No such record in this clinic (NOT_FOUND).
409	Conflict, or a request with the same Idempotency-Key is still in flight (IDEMPOTENCY_IN_PROGRESS).
422	Validation failed (VALIDATION_ERROR), or the Idempotency-Key was used for a different request (IDEMPOTENCY_KEY_REUSED).
422	Validation failed (VALIDATION_ERROR).
429	Per-client rate limit exceeded (RATE_LIMITED).
500	Unexpected error (INTERNAL_ERROR).

Rate limiting (429) and what to retry are covered in Rate limits and Retrying.