Error handling

This section outlines some of the most common errors encountered when integrating with the Demand API, along with recommended solutions.

Overview

When integrating with the Demand API, your application should include error handling logic to manage any issues that may arise during requests to API endpoints.

There are two primary types of errors your integration should be prepared to handle:

Network connection failure

If a network connection fails before the client receives a response, the request status is indeterminate. The request could have:

• Completed successfully but failed before the response reached the client.
• Failed while being processed by the server.
• Never reached the endpoint.

In general if our service is inaccessible for any reason, then a 503 - Service unavailable error will be retrieved.

Recommendation

We recommend using a retry mechanism with exponential backoff and limit the number of retries.

If the issue persists after the retry limit is reached, contact Booking.com for assistance.

HTTP Status codes

The Demand API uses standard HTTP response codes, as defined in RFC 2616 and RFC 6585, to communicate the outcome of an API request.

200 - OK

The request was successful, and the response contains the requested data.

Refer to the endpoint's entry in the API Reference for further details.

General error codes

400 - Bad request

Description: The request URL or body sent by the client is malformed or contains invalid data.

The response body contains further details such as:

{
   "request_id": "01gw5aaj8dkh7fvgwa7phs916x",
   "errors": [
       {
           "id": "missing_parameter",
           "name": "Missing Parameter",
           "message": "Parameter 'checkin' is missing."
       }
   ]
}

This response only identifies the first error found when processing the request; it does not mean that this is the only error present. If there are further errors, the next one will be found and reported when you retry the request.

Cause: The errors.id field in the response identifies the specific client error that has occurred - see Client error ids. The errors.message field provides more details about the error.

Solution: Review the request format, parameter values, and ensure all required parameters are included.

401 - Unauthorised

Description: Access is denied due to invalid authentication credentials.

Possible causes:

• Missing or incorrect Authentication header.
• Invalid or revoked API key.
• Missing or incorrect X-Affiliate_Id header.

Solution:

• Ensure the Authentication and/or X-Affiliate_Id headers are correct and up to date and retry the request.
• In case of an invalid or revoked API key, you can try to generate a new one.

403 - Forbidden

Description: The API user identified in the request does not have permission to access this endpoint. For more details refer to the Authentication and authorisation guide.

Possible causes:

• Incorrect affiliate id.
• The API user lacks permissions to access the endpoint.

Solution:

• Correct the request's X-Affiliate_id header if the id used was wrong. Then retry the request.
• If the API user needs access, contact Booking.com to request permission.

404 - Not found

Description: The requested endpoint could not be found.

Possible causes:

• The request URL is correct, but the endpoint is currently unavailable.
• The URL itself is incorrect.

Solution: Review and correct the URL as needed. (Refer to the API Reference for endpoint details.) Then retry the request.

405 - Method not allowed

Description:

• The HTTP method used is not allowed for the requested endpoint.
• Only POST is supported for all Version 3.x Demand API endpoints. All other methods are not supported.

Solution:

• Ensure the request uses the POST method with the appropriate body. (Refer to the API Reference for further details.)
• Then retry the request.

406 - Not acceptable

Description:

• This error typically occurs when the Accept header in the request does not specify that JSON is as an acceptable format for the response.
• All Demand API endpoints return JSON responses.

Solution:

• Correct the Accept header to include JSON as an acceptable format (for example: Accept: */* or Accept: application/json).
• Then retry the request.

Here’s an example of how the Accept header should be set in your request:

Accept: application/json

409 - Order unavailable

Description: This error has to do with order-related issues.

There are two reasons and messages around it:

Causes:

1. When trying to cancel an order without "Booked" status, this message appears:

The order cannot be cancelled due to its current state (e.g. stayed).

2. When the order has an unavailable item, the error points it out.

For example, for this request:

'{  
    "accommodation": {  
            "id": 10507360,  
            "checkin": "2024-12-28",  
            "checkout": "2024-12-29",  
            "products": [  
      {  
        "id": "1050736003_377312697_0_2_0",  
        "allocation": {  
          "children": [],  
          "number_of_adults": 1  
        }  
      }  
            ]  
    },  
    "booker": {  
            "country": "nl",  
            "platform": "desktop"  
    },  
    "currency": "EUR"  
}' 

The response identifies that the product with id 1050736003_377312697_0_2_9 is no longer available.

{  
"request_id": "01jdvwg49wz2dexwehzrncea27",  
"errors": [  
    {  
        "id": "order_unavailable",  
        "message": "Order has unavailable items: product '1050736003_377312697_0_2_9' for this order is unavailable."  
    }  
]  
} 

Solution:

• If attempting a cancellation, ensure the order is in a valid state (example: "booked").
• If a product is no longer available, in orders/preview or orders/create, go back to accommodation/availability and select an available alternative.

415 - Unsupported media type

Description: The request payload format is unsupported.

Causes: This means the server is rejecting the request because:

• It doesn’t support the media type specified in the Content-Type header.
• The Content-Type header is missing or does not include JSON as an acceptable format for the request.

This happens if the server is expecting a different format or if it doesn’t recognise the charset=utf-8 parameter.

Solution:

• Correct the Content-Type header to include JSON as an acceptable format (for example: Content-Type: application/json).
• Then retry the request.

429 - Too many requests

Description: Rate limiting has been triggered due to an excessive number of requests.

Cause:

• The partner account associated with the API user making this call has sent too many requests to the Demand API in a given time period.
• As a result, all requests from this API user are currently being rejected with a 429 response.
• See Rate limiting for more information.

Solution:

• Retry the request, using a retry mechanism that incorporates an exponential backoff schedule and a limit on the number of retries (and/or the maximum duration between retries).
• If the issue persists after the retry limit is reached, stop retrying and contact Booking.com for assistance.

5xx - Internal server error

Description: Temporary system failure.

• The server encountered an issue preventing it from fulfilling the request.

Cause:

• These errors cover all server-side problems that may occur in the Booking.com system.
• Depending on the issue, a response body containing more details may or may not be returned.
• If you are attempting to cancel an order for a third-third_party_inventory property, this error may be related to the cancellation policy associated to it. Please review the cancellation restrictions that apply to these type of properties.

Solution:

• If specific instructions are provided in the response, follow them.
• Otherwise, retry the request using exponential backoff. If the issue persists, contact your Account Manager for further assistance.

Client error ids

The following sections provide a detailed explanation of the specific error responses that are returned when a request fails with an HTTP 400 status code, following this pattern:

"request_id": "585235e6e20541dab7a631cc03c8fa1a",
"errors": [{
  "id": "unknown_parameter",
  "message": "Parameter 'dummy' does not exist."
}]

Conflicting parameters

Description: The request body contains one of the following problems:

• One or more parameters that cannot be used together in the same request.

  Solution: Remove the conflicting parameter(s).

• Two parameters that have conflicting values.

  Solution: Correct the parameter values.

Example 1 - Conflicting parameters:

curl -L -X POST 'https://demandapi-sandbox.booking.com/3.1/accommodations/search'
...
{
  "country": "nl",
  "city": -2140479,
  ...
}

Example 2 - Conflicting 'Page' parameter:

When a page parameter (field) is used the request must contain no other parameters.

curl -L -X POST 'https://demandapi-sandbox.booking.com/3.1/accommodations/search'
...
{
  "city": -2140479,
  "page": "eyJhbGciOiJIUzI1NiJ9.eyJwIjp7ImNvdW50cnkiOiJ1cyIsImluZGV4IjoiS05LIn0sImF1ZCI6IkNPTU1PTl9MT0NBVElPTlNfQUlSUE9SVFMiLCJleHAiOjE2Nzk1NzIyMTF9.YDh-rCV9wuXtxQGUZG9aZ3G1oYrSjk6TSftWbV2Bbng",
  ...
}

Example 3 - Conflicting parameter values:

curl -L -X POST 'https://demandapi-sandbox.booking.com/3.1/accommodations/search'
...
{
  ...,
  "checkin": "2023-08-17",
  "checkout": "2023-08-16",
  ...
}

Expired token

Description: The request contains a pagination token that is no longer valid because it has expired. Pagination tokens expire 1 hour after they are generated.

Solution:

1. Repeat the original call to the endpoint to get the first page of results. The response includes a new pagination token (in the next_page field) for retrieving subsequent pages.

2. Within 1 hour, call the endpoint again to get the next page of results.

   • Use the new pagination token from the previous response as the only parameter in the request (in the page field).
   • If the response contains a next_page field, there are more results available. If it does not, you have reached the end of the results.

3. Repeat step 2 until all results have been retrieved.

Example response:

{
   "request_id": "01gw74d6yddk07fa11g4psnfrb",
   "errors": [
       {
           "id": "expired_token",
           "name": "Expired Token",
           "message": "Token 'page' has expired."
       }
   ]
}

Invalid request

Description: The request is invalid due to one of the following reasons:

Body is absent

The request does not include a request body but this endpoint requires one.

Solution: Include a request body with the required content.

Query string

The request URL contains one or more query parameters in the request URL.

• Version 3 Demand API endpoints do not accept query parameters.
• You must pass all parameters as fields in the request body.

Solution:

• Remove the query parameters and include fields in the request body.
• Check the Quick guide for basic instructions on constructing requests.

Example request- Query string:

curl -L -X POST 'https://demandapi-sandbox.booking.com/3.1/accommodations/availability?affiliate_id=123'
...

Children in "Adults only" properties

Description: When searching for accommodations that include children in the request, if the selected property is an "Adult only" one, then the Orders/preview endpoint returns an error.

This is a safeguard to prevent users from booking "Adults Only" properties when children are part of the search group.

Solution:

• To book child-friendly accommodations, ensure you are searching for properties that are not "Adults Only."

• You can use the accommodations/details endpoint to identify "Adults Only" properties in advance.

{
  "booker": {...},
  "currency": "EUR",
  "accommodation": {
    "id": 600455,
    "checkin": "2025-02-21",
    "checkout": "2025-02-25",
    "products": [
      {
        "id": "60045504_87857366_85_0_489717",
        "allocation": {
          "number_of_adults": 1,
          "children": [
            8
          ]
        }
      },
...

Invalid token

Description:

• The request body contains an invalid pagination token.
• This occurs when the token value does not match any valid token.

Solution: Ensure the token is the same as the one returned in the next_page field of the previous response.

Example response:

{
   "request_id": "01gw6zzmcrnnjcaqzt95a1t171",
   "errors": [
       {
           "id": "invalid_token",
           "name": "Invalid Token",
           "message": "Token 'page' is invalid."
       }
   ]
}

Invalid value

Description:

• The request body contains a parameter with an invalid value.
• This could be due to an incorrect type, format, or an invalid entry in an enumerated list.

Solution: Correct the parameter value. Refer to the endpoint's entry in the API Reference for details of the parameter.

Example 1 - Invalid type:

Parameter with the wrong type - an integer defined as a string.

curl -L -X POST 'https://demandapi-sandbox.booking.com/3.1/accommodations/search'
...{
  ...
  "guests": {
      "number_of_rooms": "3",
      "number_of_adults": 5,
      "children": [2,3,13,15]
      },
  ...
}

Example 2 - Invalid date format:

Parameter with an invalid format for the checkin date

curl -L -X POST 'https://demandapi-sandbox.booking.com/3.1/accommodations/search'
...
{
  ...,
  "checkin": "23-08-15",
  "checkout": "2023-08-16",
  ...
}

Example 3 - Invalid enum value:

Example of invalid enum (rooms) in an enumerated list.

curl -L -X POST 'https://demandapi-sandbox.booking.com/3.1/accommodations/search'
...
{
  ...,
  "extras": ["products","rooms"],
  ...
}

Invalid parameter

Description: This can be returned when leaving quotation marks without parameter in the body request.

Solution: Check the identified parameter in the message and amend when possible. In this example, remove quotation marks and add the accepted parameter (desktop, mobile, etc.).

Example : In this example the platform parameter is not included inside the quotation marks.

{
  "accommodation": 10004,
  "booker": {
    "country": "nl",
    "platform": ""
  },
  "checkin": "2025-02-15",
  "checkout": "2025-02-18",
  "extras": [
    "extra_charges"
  ],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}

Malformed request

Description: The request body contains one or more syntax errors, making the JSON object invalid.

Solution: Correct and validate the JSON syntax.

Example request - Missing comma:

• In this example, a comma is missing after "AMS".
• The comma is needed to separate the airport and languages objects.

{
   "airport": "AMS"
   "languages": [
       "en-gb",
       "zh-cn"
   ]
}

Missing parameter

Description: The request body does not contain a required parameter.

This may be:

• A specific named parameter.
• A parameter from a mutually exclusive set.

Solution:

• Add the required parameter.
• Check the API Reference for more details on required parameters.

Example 1 - Missing specific parameter:

The request has left out a specific parameter.

{
  "accommodation": 10004,
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkout": "2025-02-18",
  "extras": [
    "extra_charges"
  ],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}

Example 2 - Missing parameter from mutually exclusive set:

The request has left out a parameter from a mutually exclusive set.

Response:

{
   "request_id": "01gw59jvtytrkn653tzq0nggcq",
   "errors": [
       {
           "id": "missing_parameter",
           "name": "missing parameter",
           "message": "One of the parameters in the list '[accommodations, airport, city, coordinates, country, district, landmark, region]' is missing."
       }
   ]
}

Token endpoint mismatch

Description:

• The request contains a pagination token generated by a different endpoint, making it invalid for the current endpoint.
• A pagination token can only be used in a call to the same endpoint that generated it.

For example, a pagination token generated by the /accommodations/cities endpoint cannot be used in a call to the /accommodations/countries endpoint.

Solution:

• Replace the invalid pagination token with the one returned from the same endpoint.

• If the correct pagination token is not available:

1. Repeat your original call to the endpoint to get the first page of results.

   • The response includes a new pagination token (in the next_page field) which you must use to get the next page.

2. Within 1 hour, call the endpoint again to get the next page of results.

3. Use the new pagination token from the previous response as the only parameter in the request (in the page field).

   If the response contains a next_page field, there are more results available. If there is no next_page field, you have reached the end of the results.

4. Repeat until you have received all of the available results.

Example response:

{
   "request_id": "01gw6zjf8n3kvw68jt39g8kcxp",
   "errors": [
       {
           "id": "token_endpoint_mismatch",
           "name": "Token-endpoint Mismatch",
           "message": "Token 'page' cannot be used in this endpoint."
       }
   ]
}

Unknown parameter

Description: The request contains a parameter name that is not recognised by the endpoint's schema.

Solution:

• Correct the parameter name.
• Refer to the API Reference for valid parameters.

Example response:

{
   "request_id": "01gw5ahxqve7gsd7k62ps3bswv",
   "errors": [
       {
           "id": "unknown_parameter",
           "name": "Unknown Parameter",
           "message": "Parameter 'accommodation' does not exist."
       }
   ]
}