Guides

Errors

Every refusal names a code. Branch on the code, not on the status: three different 403s want three different fixes.

The envelope

Errors are always JSON and always carry error and code. A 422 additionally carries details, which maps each rejected attribute to its reasons so a client can put the message next to the field that caused it.

422

{
  "error": "Validation failed",
  "code": "validation_failed",
  "details": {
    "email": ["is invalid"],
    "name": ["can't be blank"]
  }
}

401Authentication

unauthorizedfix first
No key, or the token does not resolve to one.
key_revokedfix first
The key existed and was switched off. Issue a new one.
key_expiredfix first
The key passed its expiry date. Issue a new one.

402Quota

search_quota_exhaustedfix first
The month's searches and the search wallet are both used up. Buy a pack or wait for the reset.

403Permission

ip_not_allowedfix first
The credential is fine, the source address is not on the key's allowlist.
plan_upgrade_requiredfix first
The account's plan does not include API access at all.
insufficient_scopefix first
The key is narrow and this endpoint is outside it.
forbiddenfix first
The role bound to the key does not permit this operation.
plan_gatedfix first
The plan does not include this particular report.
misconfiguredfix first
The account has no active owner for the key to act as. The agency must fix this.
traveler_scopefix first
A traveller token was presented outside its own routes.
addon_requiredfix first
The account lacks an add-on this surface needs; `details.missing` names it.

404Not found

not_foundfix first
No such record, or it belongs to another account.
unknown_entityfix first
The import entity key is not in the registry.
operation_not_foundfix first
No operation by that id for this key: expired (a hold, ticket, release or purchase sent with an `Idempotency-Key` is kept 7 days, any other call 15 minutes), it can no longer be read, or another key's. On a hold, ticket or purchase, send the call again with the same `Idempotency-Key` and body; it replays the first answer or answers `booking_unresolved` with the booking its key claimed. Send a release again as it was. Do not refund the card on this answer alone.

409Conflict

idempotency_conflictretry
The first call with this key is still running. Wait out `Retry-After` and send it again; once the first one is done the repeat replays its answer.
price_changedfix first
The fare moved. Price the offer again and confirm the new total with your customer.
approval_requiredfix first
The agency approves this ticket first. Call ticket again once it is approved.
credit_blockedfix first
The buyer's credit limit does not allow this hold.
supplier_balancefix first
The agency's balance with the supplier does not cover this ticket.
journey_partialfix first
Some tickets of a multi-part journey were issued and one was not.
hold_expiredfix first
The hold is no longer open. Search again.
not_cancellablefix first
This booking can no longer be released here.
no_connectionfix first
The agency has no supplier connection that can serve this call.
not_supportedfix first
The supplier connection does not support this call.

410Expired

offer_expiredfix first
The search or the offer has expired. Search again.

422Rejected

validation_failedfix first
The record was rejected. `details` names the fields.
idempotency_key_reusefix first
That key was already used for a different body or path.
entity_not_writablefix first
The entity broadcasts and can be read, but cannot be pushed.
no_rowsfix first
The ingest body carried no rows.
too_many_rowsfix first
The batch is over the per-request row ceiling. Split it.
no_companyfix first
The account has no company to file the rows against.
unknown_branchfix first
The `branch_id` is not one of this account's. `GET /api/v1/workspace` lists them.
invalid_stagefix first
No such lead stage.
conversion_failedfix first
The lead could not be converted. Usually it already was.
provider_rejectedfix first
The supplier refused the request; `details.provider_message` carries its reason.
payment_mismatchfix first
The payment amount or currency differs from the booking total.
merchant_account_requiredfix first
Name the POS the payment was taken on (`payment.merchant_account_id`).
idempotency_key_requiredfix first
This call moves money or seats and needs an `Idempotency-Key` header.
invalid_price_tokenfix first
The price token is missing, expired or belongs to another offer. Price again.
payer_requiredfix first
The booking has no cari to bill and the payment needs one. Send `bill_to` with a VKN, a TCKN or a passport, or `customer_id`.

429Rate limit

rate_limitedretry
Too many calls in this window. Wait out `Retry-After`.

502Unresolved

booking_unresolvedfix first
The supplier's answer is unknown, or the call did not finish in 3 minutes. Read the booking back (`booking_id`) and refund only if it was not ticketed. A hold, ticket or purchase keeps this answer under its `Idempotency-Key`; a new attempt takes a new key.

503Temporary

suggestions_failedretry
The suggestion engine could not answer. Transient.
provider_unavailableretry
The supplier could not be reached, the call could not be queued, or a search, price or rules call did not finish in 3 minutes. Nothing was booked, and a search costs nothing when this happens.