Errors and pagination

Error envelope

Every non-2xx response uses a single, consistent envelope so clients can key on
a stable machine-readable code and drive recovery from recoveryAction:

{
  "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.
`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.

Pagination

List endpoints use offset-based pagination via limit and offset query
parameters and return a JSON array of items:

GET /v1/bookings?limit=20&offset=0

To page forward, increase offset by limit. When a response returns fewer
items than limit, you have reached the end. Combine with the endpoint's
filters (for example status, vertical, or date bounds on GET /v1/bookings)
to narrow results.

Versioning and compatibility

All endpoints are versioned under /v1. Within a version, Mercury holds these
compatibility guarantees:

Response fields are not removed, renamed, or narrowed in type.
No new required request field is added.
Enum values are not removed.

Backward-incompatible changes are shipped under a new path prefix (/v2)
rather than by mutating /v1. New optional request fields and new response
fields can be added within /v1 and should be tolerated by clients.

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.