Client error codes and examples

This page describes common errors codes (ids) you may encounter when using the Demand API. It includes clear explanations, sample responses, and actionable guidance.

Overview

These client-side errors occur when the request is invalid due to incorrect data or missing parameters—commonly referred to as a "bad request".

Each error response includes:

Key fields	Description
`errors.id`	A machine-readable error code (such as `missing_parameter`) It replaces the deprecated `error.code` or `error.name` (used in V2).
`errors.message`	A human-readable explanation along suggested solutions.

Best practices

✅ Validate your request structure and data before sending.

✅ Consult the [API Reference](API Reference) for required fields.

✅ Follow the Quick guides and Pagination guide.

✅ Fix the first reported error and retry — additional errors may surface sequentially.

Error codes (ids)

Below are common client error codes, their causes, and how to resolve them.

Conflicting parameters

Description - This error is returned when the request body contains:

Parameters that cannot be used together.
Two parameters that have conflicting values.

Example 1 - Mutually exclusive parameters

Using city and country together in the search request:

{
  "booker": {
    "country": "gb",
    "platform": "desktop"
  },
  "checkin": "2025-09-12",
  "checkout": "2025-09-14",
  "city": -2612321,
  "country": "gb"
}

The response:

{
  "request_id": "01gw5m6dfme725bbvcthz0gde0",
  "errors": [
    {
      "id": "conflicting_parameters",
      "message": "Parameters city and country are mutually exclusive."
    }
  ]
}

Example 2 - 'Page' must be used alone

When using pagination, page is included and no other parameters are allowed.

curl -L -X POST 'https://demandapi-sandbox.booking.com/3.1/accommodations/search'
...
{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkin": "2025-10-02",
  "checkout": "2025-10-05",
  "city": -2140479,
  "guests": {
    "number_of_adults": 2
  },
  "page": "eyJhbGciOiJIUzI1NiJ9.eyJwIjp7ImJvb2tlciI6eyJjb3VudHJ5IjoibmwiLCJwbGF0Zm9ybSI6ImRlc2t0b3AifSwiY2hlY2tpbiI6IjIwMjUtMTAtMDIiLCJjaGVja291dCI6IjIwMjUtMTAtMDUiLCJjaXR5IjotMjE0MDQ3OSwiZ3Vlc3RzIjp7Im51bWJlcl9vZl9hZHVsdHMiOjIsIm51bWJlcl9vZl9yb29tcyI6MX0sIm9mZnNldCI6MTAwfSwiYXVkIjoiL2FjY29tbW9kYXRpb25zL3NlYXJjaCIsImV4cCI6MTc0OTgyNTI1NH0.dg1C-3LnmS6BdGw8QZJj3NsbAcGGA7f6jYRAgpTWxsM"
}

Response:

{
  "request_id": "01gw6zpn448k8vm60wpbqtg8vn",
  "errors": [
    {
      "id": "conflicting_parameters",
      "message": "Parameter 'page' is exclusive with all other parameters."
    }
  ]
}

Solution - Remove all the unnecessary fields from the request and leave "page" only:

{
"page": "eyJhbGciOiJIUzI1NiJ9.eyJwIjp7ImJvb2tlciI6eyJjb3VudHJ5IjoibmwiLCJwbGF0Zm9ybSI6ImRlc2t0b3AifSwiY2hlY2tpbiI6IjIwMjUtMTAtMDIiLCJjaGVja291dCI6IjIwMjUtMTAtMDUiLCJjaXR5IjotMjE0MDQ3OSwiZ3Vlc3RzIjp7Im51bWJlcl9vZl9hZHVsdHMiOjIsIm51bWJlcl9vZl9yb29tcyI6MX0sIm9mZnNldCI6MTAwfSwiYXVkIjoiL2FjY29tbW9kYXRpb25zL3NlYXJjaCIsImV4cCI6MTc0OTgyNTI1NH0.dg1C-3LnmS6BdGw8QZJj3NsbAcGGA7f6jYRAgpTWxsM"
}

Example 3 - Conflicting date values

In this example the checkout date happens before the checkin date:

{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkin": "2025-10-12",
  "checkout": "2025-10-05",
  "city": -2140479,
  "guests": {
    "number_of_adults": 2
  },

The response:

{
  "request_id": "01gw57qeem57a92f4z8dgfsc3t",
  "errors": [
    {
      "id": "conflicting_parameters",
      "message": "Parameters 'checkin' and 'checkout' have conflicting values. The checkout date must be after the checkin date."
    }
  ]
}

Solution - Ensure the checkout date is later than checkin.

For more information on the affected parameters, consult the endpoint's entry in the API Reference.

Expired token

Description - Returned when the pagination token is older than 3 hours.

Example response:

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

Solution:

Repeat the original request to retrieve a new next_page token.
Use the new token in the page field within 3 hours.
- 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.
Repeat the process until the response no longer includes a next_page field in the response.

Admonition name

See the Pagination guide for more details.

Invalid request

Indicates the request is not correctly structured.

Example 1 - Query string used

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.

Example request- Query string:

The URL contains a query string, ?affiliate_id=12345.

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

The response returns the error:

{
  "request_id": "01gw4mwegd1pbb66xbh0whtkaw",
  "errors": [
    {
      "id": "invalid_request",
      "message": "Query string provided but none expected."
    }
  ]
}

Solution:

Remove query parameters from the URL.
Include all parameters in the request body.

Check the Quick guide for basic instructions on constructing requests.

Example 2 - Children in "Adults only" properties

When searching for accommodation including children as guests in the request, if the selected property is "Adult only", 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 booking group.

Here’s an example of an orders/preview request with children included:

{
  "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
          ]
        }
      }
    ]
  }
}

The response will return this error:

{
  "request_id": "01jj1y1gr17zd462n9655d329g",
  "errors": [
    {
      "id": "invalid_request",
      "message": "Children are not allowed in this 'Adults only' property. Please select a child-friendly accommodation."
    }
  ]
}

Solution:

Avoid selecting adults-only properties when children are part of the booking group.
Use the accommodations/details endpoint to identify "Adults Only" properties in advance.

See the Family use cases section for guidance.

Invalid token

Description - Returned when the page token is not recognised.

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

Solution - Use the exact next_page token received in the previous response.

Token endpoint mismatch

Description:

The request contains a page 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.

Example error response:

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

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

If the correct pagination token is not available:

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.
Use this token in a follow-up request within 3 hours.
- Use the new pagination token from the previous response as the only parameter in the request (in the page field).
Repeat until the response contains no next_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.

Invalid parameter

Description - Returned when a field contains an invalid type, format, or value or when a parameter is present but empty or malformed.

Example 1 - Wrong type

Search request with an integer instead of an array:


}
  "checkin": "2025-10-02",
  "checkout": "2025-10-05",
  "city": -2140479,
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1,
    "children": 2, 3, 13, 15,
  }
}

The response:

{
  "request_id": "01jxmk773ff9r7nabwn6nn0bm2",
  "errors": [
    {
      "id": "invalid_parameter",
      "message": "Parameter 'guests.children' is invalid. Expected: array. Actual: integer."
    }
  ]
}

Solution - Use an array in the request instead:

{
  "checkin": "2025-10-02",
  "checkout": "2025-10-05",
  "city": -2140479,
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1,
    "children": [2, 3, 13, 15] 
  }
}

Example 2 - Invalid date format

Parameter with an invalid format for the checkin date:

{
  "checkin": "25-10-02",
  "checkout": "2025-10-05",
  ...
  }
}

The response:

{
  "request_id": "01gw7p7mp43dccs5zje3gezwkc",
  "errors": [
    {
      "id": "invalid_parameter",
      "message": "Parameter 'checkin' is invalid."
    }
  ]
}

Example 3 - Invalid enum value

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

...
  "checkin": "2025-10-02",
  "checkout": "2025-10-05",
  "city": -2140479,
  "extras": ["products","rooms"],

The response:

{
  "request_id": "01gw5btwz6k3b6ajprx36hm6d4",
  "errors": [
    {
      "id": "invalid_parameter",
      "message": "Parameter 'extras[1]' is invalid."
    }
  ]
}

Example 4 - Invalid country format

If the response returns this error:

{
  "request_id": "01jxmm46dyve00kcp00s0pzead",
  "errors": [
    {
      "id": "invalid_parameter",
      "message": "Parameter 'booker.country' is invalid."
    }
  ]
}

Double check the country code you included in request is not in Capitals, but in lowercase "nl".

Missing value

In this example, the value "desktop" or "mobile" is missing.

{
  "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
  }
}

The error response:

{
  "request_id": "01jh2n6afwrks4406kt7temrg3",
  "errors": [
    {
      "id": "invalid_parameter",
      "message": "Parameter 'booker.platform' is invalid."
    }
  ]
}

Solution - Remove quotation marks and use a valid value like "desktop" or "mobile".

Malformed request

Description - Returned when the JSON structure is invalid (e.g. missing comma or bracket).

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"
  ]
}

The response:

{
  "request_id": "01gw4zdfk13cbvbb1ktr679pbg",
  "errors": [
    {
      "id": "malformed_request",
      "message": "Unexpected character ('\"' (code 34)): was expecting comma to separate Object entries."
    }
  ]
}

Solution - Correct and validate the JSON syntax.

Missing parameter

Description - Returned when a required parameter is absent.

This may be:

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

Example - Missing checkin

The request has left out a specific parameter (checkin field)

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

The error response:

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

Solution:

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

Unknown parameter

Description - The request contains a parameter that is not recognised by the endpoint schema.

Example response:

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

Solution:

Check for typos or incorrect parameter names.
Refer to the API Reference for the list of supported parameters.

Curious to know more?

Authentication guide - Make sure your requests are properly authenticated to avoid 401/403 errors.
OpenAPI reference - Check parameter requirements and valid combinations for each endpoint.
Pagination guide - Learn how to correctly use the page parameter and avoid conflicts with search filters.
Order cancellation errors - Handle client errors specific to order cancellation.
Payment errors- Understand client-side issues during payment flows.
HTTP 4xx status code scenarios - A complete guide to 4xx status codes used by the Demand API.

Client error codes and examples

Overview

Best practices

Error codes (ids)

Conflicting parameters

Example 1 - Mutually exclusive parameters

Example 2 - 'Page' must be used alone

Example 3 - Conflicting date values

Expired token

Invalid request

Example 1 - Query string used

Example 2 - Children in "Adults only" properties

Invalid token

Token endpoint mismatch

Invalid parameter

Example 1 - Wrong type

Example 2 - Invalid date format

Example 3 - Invalid enum value

Example 4 - Invalid country format

Missing value

Malformed request

Missing parameter

Example - Missing checkin

Unknown parameter

Related topics

Was this helpful?