Errors

Errors use standard HTTP status codes and a consistent JSON envelope:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the 'bookings:write' scope.",
    "requestId": "9f1c2f2a-6f6e-4c0a-8d55-1b1f3d6b9a77",
    "details": null
  }
}

code is stable and machine-readable — branch on this, not on message.
requestId is also returned in the X-Request-Id response header. Quote it when contacting support; it lets us find the exact call.
details is present for validation errors and lists each failing field: [{ "path": "adults", "message": "…" }].

Codes

HTTP	`code`	Meaning
400	`bad_request`	Validation failed (see `details`)
400	`idempotency_key_required`	`POST /bookings` sent without an `Idempotency-Key`
401	`unauthorized`	Missing, invalid, revoked or expired key; bad signature or timestamp
403	`forbidden`	Client suspended, or the request came from an IP not on the key's allow-list
403	`insufficient_scope`	The key lacks the required scope
403	`scope_disabled`	The scope is switched off platform-wide
403	`client_not_linked`	The client is not linked to a tenant (needed for bookings and invoices)
404	`not_found`	Unknown resource, or one that belongs to another organisation
409	`conflict`	State conflict, e.g. cancelling a booking that is not `Upcoming`
410	`offer_expired`	The `offerToken` is older than 15 minutes — search again
422	`idempotency_key_reuse`	The same `Idempotency-Key` was used with a different body
429	`rate_limited`	Per-key rate limit exceeded; see `Retry-After`
503	`api_disabled`	The API is switched off by the platform administrator
500	`internal_error`	Unexpected server error — retry with backoff and report the `requestId`

Retrying safely

5xx and 429: retry with exponential backoff and jitter; honour Retry-After.
POST /bookings: always send an Idempotency-Key, and reuse the same key when retrying — you will get the original result and never a duplicate booking. See Pagination & idempotency.
4xx other than 429: do not retry unchanged; fix the request.