Errors

Every error response carries a stable machine-readable code, and every status code maps to a defined condition.

Error envelope

Every error on this API has the same shape. One handler covers the whole surface, including authentication failures and unrouted paths. The single exception is the OAuth token endpoint, which follows the RFC 6749 error body (error, error_description) as the OAuth standard requires. See Authentication.

{
  "error": {
    "code": "BOOKING_NOT_CANCELLABLE",
    "message": "booking is not cancellable",
    "trace_id": "0f2c9d6e-7b1a-4c3e-9a2f-1d6e7b1a4c3e",
    "retryable": false
  }
}

code, message, trace_id, and retryable are always present. When the request omits X-Request-Id, the API generates trace_id. When the request includes X-Request-Id, the API echoes that value as trace_id for correlation.

Status-code reference

Response handling

On GET /properties and GET /bookings, an invalid or obsolete cursor is 400 INVALID_REQUEST with field=cursor; restart the lookup from its first page. On GET /catalog/changes, an invalid cursor is 400 INVALID_CURSOR, while a cursor that can no longer continue is 409 CATALOG_VERSION_CHANGED: rebuild the property snapshot and resume from its terminal changes_cursor.

• Branch on code, never on message. Codes are stable; messages are not.
• Retry only the retryable. Retry eligible 429, 500, and 503 responses with bounded backoff and jitter; honor Retry-After on 429 and 503. 401 is retryable after refreshing the token. 400, 403, 404, 409, 410, and 422 indicate a request or state problem and will not be fixed by an unchanged retry. PREBOOK_EXPIRED (409) succeeds after a fresh prebook. Every error carries a retryable boolean stating this directly, so prefer it over inferring from the status code.
• Retry writes with the same idempotency key. When retrying book, re-send the same Idempotency-Key and identical body so the retry replays rather than duplicates. See Idempotency.
• Keep the trace_id. Every error response carries one, including the 401 you get before authenticating; log it so a single request can be traced end to end in a support enquiry.

Per-property search failures

POST /properties/availability returns 200 when an individual property fails. The failure surfaces inline on results[i].error_code: PROPERTY_NOT_FOUND, UNSUPPORTED_FX_PAIR, SEARCH_WORK_LIMIT_BREACH, SEARCH_TIMEOUT, SUBSTRATE_DATA_INVARIANT, or INTERNAL_ERROR. Inspect every result. Two request-level failures are exceptions: search capacity exhaustion returns top-level 503 SEARCH_OVERLOADED, and a deadline before any row completes returns top-level 503 SEARCH_TIMEOUT. Both carry Retry-After. SEARCH_TIMEOUT is the only retryable inline code; keep every other row and retry only the affected property IDs with bounded backoff. Preserve their relative order and all other search fields. For an inline timeout response, even if the first request omitted it, set request_time to the first response's request_time on every retry. If a retry does not reduce the timeout set, partition the remaining IDs into smaller ordered batches (for example, halves) before the next attempt. Continue within an overall retry/time budget; a single-property timeout may be retried with backoff, but SEARCH_WORK_LIMIT_BREACH is deterministic and must not be retried unchanged.

On an initial availability request, a client-supplied request_time may be at most 30 days behind or 60 seconds ahead of the server clock; both boundaries are inclusive. A value outside the inclusive [server_time - 30 days, server_time + 60 seconds] window is a top-level 400 INVALID_REQUEST with field=request_time; it never appears as a per-property error_code.

For POST /places/availability, omitting request_time is safe on every page: the signed cursor restores the first page's server-resolved instant. That valid cursor-carried fixed instant remains usable until the cursor expires, even if the server clock crosses the initial 30-day lower boundary during the walk. An explicit value on a continuation must equal the first response. Do not derive it from the HTTP Date header.

A top-level 503 has no property rows. Honor Retry-After and branch on its code. For SEARCH_OVERLOADED, reduce concurrent search pressure and retry the request. For SEARCH_TIMEOUT, no property completed before the deadline, so partition the ordered property IDs into smaller batches before retrying. Preserve the original request_time; if the original request omitted it, choose one new evaluation instant before the first partitioned retry and reuse that value across every partition.

Place search has its own request-level failures, all in the normal error envelope, none of them retryable unchanged:

The single-property detail route uses top-level status codes because it has no batch isolation boundary: 404 PROPERTY_NOT_FOUND, 422 UNSUPPORTED_FX_PAIR or SEARCH_WORK_LIMIT_BREACH, and 500 for a server failure. SEARCH_OVERLOADED and SEARCH_TIMEOUT both use 503; branch on code to distinguish them. Optional projection failures do not invalidate priced allocations; they appear as typed projection_issues inside a successful response. An issue's code is INTERNAL_ERROR when the block failed on the server, UNSUPPORTED_FX_PAIR when a fixed tax amount is kept in a currency with no current rate to your currency_code (not retryable; a currency from GET /reference/currencies may price it), or SUBSTRATE_DATA_INVARIANT when the property's stored tax data is inconsistent.

Guest age refusals

A property's guest age rules surface in three places, and only one of them is an HTTP error:

Branch on the code, never on the message. Offer the traveller another property, or a party the property accepts, instead of retrying the same request. A property's min_guest_age is in Property content, so a client can show the rule before it searches.

Mixed room settlement

422 MIXED_SETTLEMENT with field=selection_tokens refuses a selection containing both pay-at-property and prepaid rooms. Choose rooms with the same settlement route. No inventory is held.

Next steps

• Authentication: resolving 401 and 403.
• Idempotency: resolving 409 on writes.
• The booking flow: the endpoints these codes apply to.
• Booking webhooks: webhook-specific conflict and retry handling.