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

Offset-paginated list endpoints accept limit and offset query parameters
and return a page envelope:

{
  "items": [ /* ... */ ],
  "meta": {
    "totalCount": 42,
    "pageSize": 20,
    "nextOffset": 20
  }
}

GET /v1/bookings retains its legacy array response for every request.
Use the additive page operation to receive the envelope:

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

When meta.nextOffset is null, you have reached the end. Otherwise pass it
as offset on the next request. Combine with the endpoint's filters (for
example status, vertical, or date bounds on GET /v1/bookings or
GET /v1/bookings/page) to narrow results. For booking pages,
meta.totalCount is the Mercury mirror count — not a live upstream total.

Cursor-paginated endpoints (for example GET /v1/me/notifications) use a
before cursor token instead of offset; their responses use the same
meta.nextCursor field documented in the OpenAPI reference.

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.