Skip to content
Last updated

Transfers search error handling

Use this guide to understand errors returned by the transfers search endpoint and decide what to do next.


Beta version

Transfers search is a Beta endpoint. Its request and response structures may change, including through breaking changes. Check the Changelog for updates.

How to read an error response

An error response includes a request_id and an errors array. Each error contains:

  • id - A machine-readable error identifier. Transfers search validation errors use one of these IDs:

    • missing_parameter - a required field is missing.
    • invalid_parameter - a field has an invalid value, format or relationship to another field.
  • message - A human-readable explanation, which may identify the affected parameter.

For example, an invalid pick-up date and time returns invalid_parameter:

{
  "request_id": "01kjan7r7yvff5yg95gxy1cjhy",
  "errors": [
    {
      "id": "invalid_parameter",
      "message": "Parameter 'route.legs[0].pickup.datetime' is invalid. The pick-up date and time must not be in the past."
    }
  ]
}

Names such as location_not_resolvable, region_not_supported, route_not_resolvable, return_pickup_too_soon and currency_not_supported may appear as example names in the API definition. They are illustrative labels, not values returned in errors[].id.

General approach

  1. Read the id to determine whether a required field is missing or a value is invalid.
  2. Use the message to identify the parameter or issue - Correct the request using the guidance below.
  3. Send the request again after correcting it. Repeating the same request unchanged is unlikely to resolve a 400 error.
  4. If the error persists or the response is unexpected, record the request_id and contact support.

Missing parameters

A missing_parameter error means that a required field is missing from the request.

A transfers search request requires:

  • route, containing one leg for a one-way journey or two legs for a return journey.
  • A pickup.location and pickup.datetime for each leg.
  • A dropoff.location for each leg.
  • passengers.
  • currency.
  • booker.country.

For a return journey, include both legs. Each leg must specify its own pick-up and drop-off locations.

Example of missing parameters error response:

{
  "request_id": "01kjan7r7yvff5yg95gxy1cjhy",
  "errors": [
    {
      "id": "missing_parameter",
      "message": "Parameter 'route.legs[1].pickup.location' is missing."
    }
  ]
}

How to resolve

  • Add the missing field identified in the error message.
  • For a return journey, check that the second leg includes both pickup.location and dropoff.location.
  • Check the API reference for the required fields and accepted formats.

Invalid parameters

An invalid_parameter error means a field is present but its value, format or relationship to another field is invalid. The error message identifies the parameter when possible.

Invalid request structure or format

A request can be invalid if a field has the wrong type or format, does not meet field requirements, or conflicts with another field.

In the request:

  • The route.legs array must contain one leg for a one-way journey or two legs for a return journey.
  • Each location object must specify exactly one of airport, google_place_id or coordinates.

For example, this location is invalid because it specifies two identifiers:

{
  "airport": "AMS",
  "coordinates": {
    "latitude": 52.3676,
    "longitude": 4.9041
  }
}

Another example would be when the pick-up date and/or time do not use the format YYYY-MM-DDTHH:mm:ss (without a time zone or UTC offset).

This example would return this error:

{
  "request_id": "01kjan7r7yvff5yg95gxy1cjhy",
  "errors": [
    {
      "id": "invalid_parameter",
      "message": "Parameter 'route.legs[0].pickup.datetime' is invalid. 'route.legs[0].pickup.datetime' must match the format yyyy-mm-dd'T'HH:mm:ss."
    }
  ]
}

How to resolve

  • Check the field name, data type, format and accepted values.
  • Use a real calendar date and time.
  • Provide the pick-up date and time in the local time zone of the pick-up location. Do not add a time zone or UTC offset.
  • Check the API reference for the required fields and accepted formats.

Passenger count exceeds the limit

The Transfer search request supports between 1 and 8 passengers. If passengers is greater than 8, the response returns invalid_parameter with the following message.

{
  "request_id": "01kjan7r7yvff5yg95gxy1cjhy",
  "errors": [
    {
      "id": "invalid_parameter",
      "message": "The number of passengers must be 8 or fewer."
    }
  ]
}

How to resolve

  • Check that the passenger count is accurate and is between 1 and 8.
  • If more than 8 people are travelling, arrange separate searches only if your product supports multiple transfer journeys. Do not reduce the passenger count below the travellers' actual requirements.

Pick-up date and time in the past

The pick-up date and time must not be in the past.

How to resolve

  • Provide a future pick-up date and time.
  • Check that the value is interpreted in the local time zone of the pick-up location.

Location cannot be resolved

If a location cannot be resolved, the response returns invalid_parameter with a message explaining that the transfer service could not resolve a specified pick-up or drop-off location.

Possible causes include an airport code that does not identify a real airport, a Google Place ID that cannot be resolved, or coordinates that do not identify a usable location.

Example response:

{
  "request_id": "01kjan7r7yvff5yg95gxy1cjhy",
  "errors": [
    {
      "id": "invalid_parameter",
      "message": "Parameter 'route.legs[0].pickup.location' is invalid. The location could not be resolved."
    }
  ]
}

How to resolve

  • Check that the location identifier is correct.
  • For an airport, provide a valid three-letter IATA airport code. You can use the common/locations/airports endpoint to check the right code.
  • For coordinates, check that the latitude and longitude identify the intended location.
  • For a Google Place ID, check that it identifies the intended place.
  • If the location still cannot be resolved, try another supported identifier or a nearby location.

Pick-up or drop-off location not supported

If the transfer service does not support the requested pick-up or drop-off location, the response returns invalid_parameter. The message may not identify which end of the route caused the error.

Example:

{
  "request_id": "01kjan7r7yvff5yg95gxy1cjhy",
  "errors": [
    {
      "id": "invalid_parameter",
      "message": "Parameter 'route' is invalid. The pick-up or drop-off location is not supported."
    }
  ]
}

How to resolve

  • Check whether transfer services are supported for both locations.
  • Try a nearby location where transfer services are available, such as a supported airport.
  • If you cannot determine which location is unsupported, test the pick-up and drop-off locations separately.

No route could be found

If the locations are resolved but the transfer service cannot find a route between them, the response returns invalid_parameter.

Example response:

{
  "request_id": "01kjan7r7yvff5yg95gxy1cjhy",
  "errors": [
    {
      "id": "invalid_parameter",
      "message": "Parameter 'route' is invalid. No route could be found between the pick-up and drop-off locations."
    }
  ]
}

How to resolve

  • Check that the pick-up and drop-off locations are correct.
  • Try a different pick-up or drop-off location, or another route.
  • Do not retry the same request unchanged unless you have reason to believe the failure was temporary.

Return leg locations do not match the outbound leg

For a return journey, the second leg must reverse the outbound route. The locations must match exactly, including the identifier type and value:

  • The return pick-up must use the same location identifier and value as the outbound drop-off.
  • The return drop-off must use the same location identifier and value as the outbound pick-up.

For example, if the outbound drop-off is specified as "airport": "AMS", specify the return pick-up using "airport": "AMS" as well. Specifying the same apparent value using google_place_id does not match the airport identifier.

How to resolve

  • Compare the outbound and return locations.
  • Reuse the same identifier type and value for each matching location.
  • Check that the return pick-up matches the outbound drop-off, and that the return drop-off matches the outbound pick-up.

Return pick-up is not later than the outbound pick-up

The return pick-up date and time must be later than the outbound pick-up date and time. A return pick-up at the same time as, or earlier than, the outbound pick-up is invalid.

How to resolve

  • Set the return pick-up to a later date and time.
  • Check that both values are correct and use the local time zone of the relevant pick-up location.

Return pick-up is too soon

If the interval between the outbound and return pick-ups does not meet the transfer service's minimum requirement, the response returns invalid_parameter.

Example:

{
  "request_id": "01kjan7r7yvff5yg95gxy1cjhy",
  "errors": [
    {
      "id": "invalid_parameter",
      "message": "Parameter 'route.legs[1].pickup.datetime' is invalid. The return pick-up is too soon after the outbound pick-up."
    }
  ]
}

How to resolve

  • Choose a later return pick-up time.
  • If the minimum interval is not documented, increase the gap between the two pick-ups and retry the request.

Currency is not supported

If the requested currency is not supported for transfers search, the response returns invalid_parameter.

The currently documented supported currencies are AUD, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, IDR, ILS, JPY, NOK, NZD, PLN, RON, SEK, SGD, THB, TWD, USD and ZAR. This list may change.

Example of error:

{
  "request_id": "01kjan7r7yvff5yg95gxy1cjhy",
  "errors": [
    {
      "id": "invalid_parameter",
      "message": "Parameter 'currency' is invalid. The currency is not supported for transfer searches."
    }
  ]
}

How to resolve

  • Use a supported currency.
  • Check the latest API reference for the current supported currencies.
  • Avoid hardcoding the supported currency list in your integration.

No transfer options returned

A successful search may not return any vehicle options for the requested route and pick-up time.

Search results are based on predicted availability and pricing, and options may differ when the traveller follows a Booking.com redirect URL. In some cases, no options may be available on Booking.com.

How to resolve

  • Check that the route, pick-up date and time, and passenger count are correct.
  • If appropriate, ask the traveller to choose a nearby pick-up or drop-off location, a different route or a different time.
  • Make it clear that search results are based on predicted availability and pricing.

Server errors

A 500 response indicates an internal server error. It does not identify a request field that you can correct.

Example response:

{
  "request_id": "01kjan66dedrpbwv4m1966dzw3",
  "errors": [
    {
      "id": "500",
      "message": "Internal server error. Try again later or contact support."
    }
  ]
}

How to resolve

  1. Retry the request later.
  2. If the error continues, contact support and provide the request_id.
  3. Avoid retrying continuously. Handle repeated failures according to your integration's retry policy.

Troubleshooting checklist

CheckWhat to do
A required field is missingAdd the field identified in the error message. For a return journey, include both legs and all required locations.
A location object is invalidSpecify exactly one of airport, google_place_id or coordinates.
The passenger count is invalidProvide a value from 1 to 8.
A date or time is invalidUse a real future date in YYYY-MM-DDTHH:mm:ss format and the local time zone of the pick-up location.
A location cannot be resolvedCheck the airport code, Google Place ID or coordinates. If needed, try another supported identifier.
The region or route is unsupportedCheck both locations and try a supported nearby location or another route.
The return leg is invalidReverse the outbound locations, using the same identifier type and value, and set the return pick-up later than the outbound pick-up.
The currency is unsupportedUse a currency listed in the current API reference.
A 500 response persistsRetry later, then contact support with the request_id if the error continues.

Best practices

PracticeRecommendation
Validate before sendingCheck required fields, formats, dates, locations and return-leg relationships before calling the endpoint.
Use the returned error IDHandle missing_parameter and invalid_parameter as the actual validation IDs. Do not check for illustrative example names as error IDs.
Correct requests before retryingFix the reported issue before resending a request that returned 400.
Match return locations exactlyReuse the same identifier type and value when specifying the same location in both legs.
Distinguish location and route issuesA location may be unresolved, unsupported for transfer services, or resolved without a route between the locations. Follow the guidance for the message returned.
Keep the request IDRecord the request_id when investigating unexpected or persistent errors.
Account for Beta changesCheck the Changelog for changes to the transfers search request, response and error examples.