Errors

What this covers

Every non-2xx response from a /v1 endpoint uses one consistent error
envelope, so your client can key on a stable machine-readable code and
drive recovery from a dedicated recoveryAction hint — instead of parsing a
different shape per endpoint.

How it works

For contrast, a successful (2xx) response returns your data directly, with no
wrapper — for example, building a flight fare (POST /v1/flights/fares/build, abbreviated; see the
flights guide for the full request):

{
  "fareId": "018f2c9a-6b3e-7f21-9d4c-2b7a5e1f3c02",
  "totalPrice": { "amount": "149.90", "currency": "EUR" },
  "cabinClass": "economy",
  "isRefundable": false
}

An error response instead wraps the failure in the error envelope below:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Human-readable description of what went wrong.",
    "details": [],
    "recoveryAction": "CONTACT_SUPPORT",
    "retryAfterSeconds": null
  }
}

Field	Meaning
`code`	Stable machine-readable error code. Branch on this, not on `message`.
`message`	Human-readable description. May change; not a contract.
`details`	Array of field-level errors (see below). Empty for non-validation errors.
`recoveryAction`	Hint for what the client should do next (see table).
`retryAfterSeconds`	When present, how long to wait before retrying.

The full error-code enum and the meaning of every recovery action are published
in the OpenAPI reference under the info.x-error-contract extension, so they
never drift from the server.

Recovery actions

`recoveryAction`	What the client should do
`RETRY_NOW`	Retry the same request immediately.
`RETRY_LATER`	Retry after a delay (see `retryAfterSeconds`).
`CHANGE_PAYMENT`	Prompt the traveler for a different payment method.
`CHANGE_SELECTION`	The chosen option is gone; prompt for a different one.
`REFRESH`	What was shown is out of date; run the search again.
`CONTACT_SUPPORT`	Route the traveler to support; not self-serviceable.
`BLOCKED`	The action is not permitted; no client recovery is possible.
`FIX_INPUT`	Prompt the traveler to correct the request input.

Validation errors

A 422 populates details[] with one entry per failing field:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": [
      { "field": "passengers.adults", "code": "greater_than_equal", "message": "Input should be greater than or equal to 1" }
    ],
    "recoveryAction": "FIX_INPUT",
    "retryAfterSeconds": null
  }
}

Common codes

Some frequently encountered codes are listed below. Branch on the exact code
values published in the reference for your integration.

UNAUTHORIZED — missing or invalid bearer token.
RESOURCE_NOT_FOUND — the requested entity does not exist or is not visible.
VALIDATION_ERROR — the request body or parameters failed validation.
RATE_LIMIT_EXCEEDED — slow down; honour retryAfterSeconds.
BAD_GATEWAY / SERVICE_UNAVAILABLE — an upstream provider is unavailable.
BOOKING_CONFLICT — the booking could not proceed due to a conflicting state.

Consumer authentication failures are returned by the authentication layer with
code: CONSUMER_AUTH_REQUIRED — see Authentication.

What you need to handle

Branch on code, never message. message is human-readable and may
change between releases without notice; code is the stable contract.
Use recoveryAction to drive the next client action rather than
hand-rolling status-code-specific logic. A code usually carries the same
recoveryAction; the error codes reference marks the few
that choose it per failure reason.
Render details[] field-by-field on 422. Each entry names the failing
field, a machine-readable code, and a human-readable message; show
validation feedback next to the relevant input instead of a single generic
error.
Honour retryAfterSeconds on RETRY_LATER and RATE_LIMIT_EXCEEDED.
Retrying immediately defeats the backoff the server is asking for.
Treat BLOCKED as terminal. No retry, input change, or payment change
will make a BLOCKED action succeed.

Related guides

Pagination — paging through list endpoints.
Versioning and changelog — the /v1
compatibility policy and how changes are announced.
Authentication — the consumer HMAC and bearer
token schemes, including CONSUMER_AUTH_REQUIRED.
Bookings and trips — the Idempotency-Key
422 and other booking-specific error cases.

Reporting issues

This page is maintained by the BizAway integration team. To request changes or
report an error, contact your BizAway integration contact. Edits made directly
in the ReadMe dashboard are overwritten on the next publish.