Transfers

Transfers errors

Error envelopes, the full error catalog, and the successful responses that look like failures.

Application error

json

{
  "statusCode": 409,
  "code": "transfer_price_changed",
  "message": "The transfer price changed. Request pricing again"
}

Match on code, not on message: messages are localized and can be reworded.

Validation error

When the request itself is malformed, message is an array of problems instead of a single string.

json

{
  "statusCode": 400,
  "message": [
    "numPassengers must not be less than 1",
    "latitude and longitude must be sent together"
  ],
  "error": "Bad Request"
}

General errors

HTTP	Code	Meaning	Recommended action
`400`		The body, query or path is invalid, or contains an unknown property.	Fix the request using the `message` array.
`400`	`transfer_invalid_language`	Unsupported language.	Use a documented language value.
`400`	`transfer_invalid_currency`	Unsupported currency.	Use a supported currency.
`400`	`transfer_currency_mismatch`	Currency differs from the offer or quote.	Reuse the currency of the previous step.
`400`	`transfer_location_not_found`	A location could not be resolved.	Add city or zipcode, or send a place ID or coordinates.
`429`	`transfer_provider_error`	Temporary rate limit.	Retry with exponential backoff.
`502`	`transfer_provider_error`	The request could not be completed.	Do not assume success; keep your identifiers and read the reservation.
`503`		The price could not be confirmed right now.	Retry later; do not book and do not charge.

Tokens, pricing and booking

HTTP	Code	Meaning
`400`	`transfer_invalid_booking_token`	The token expired, was modified, or belongs to another offer.
`400`	`transfer_invalid_pricing_token`	The pricing token is invalid or inconsistent with the request.
`400`	`transfer_pricing_required`	The request has no pricing token.
`400`	`transfer_invalid_amenities`	Amenity keys are duplicated, empty, or unavailable.
`400`	`transfer_flight_info_required`	The offer requires `airline` and `flightNumber`.
`400`	`transfer_return_flight_info_required`	A round trip requires the return flight details.
`409`	`transfer_price_changed`	The quoted price is no longer valid.
`409`	`transfer_booking_in_progress`	The booking could not be accepted for this pricing token.
`410`	`transfer_pricing_expired`	The quote expired before the booking was created.

Reservations

HTTP	Code	Meaning
`400`	`transfer_booking_not_found`	The read did not carry exactly one identifier.
`502`	`transfer_provider_error`	A reservation could not be read, created, changed, tracked or cancelled.

Successful responses that are not errors

Several endpoints answer 200 with a negative outcome. These are results, not failures, and must be read from the body:

isValid: false on flight verification — the flight does not fit the pickup time.
cancelled: false or refunded: false on cancellation.
status: "failed" on booking or change confirmation.
An empty flights array on flight lookup.
An empty response object on tracking, before the journey starts.

Always read the body of a 200 before telling the traveller that something succeeded.