# 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](/demand/docs/open-api/demand-api/)) for required fields. ✅ Follow the Quick guides and [Pagination guide](/demand/docs/development-guide/pagination). ✅ 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: ```json { "booker": { "country": "gb", "platform": "desktop" }, "checkin": "2026-09-12", "checkout": "2026-09-14", "city": -2612321, "country": "gb" } ``` The response: ```json { "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](/demand/docs/development-guide/pagination), `page` is included and no other parameters are allowed. ```json curl -L -X POST 'https://demandapi-sandbox.booking.com/3.1/accommodations/search' ... { "booker": { "country": "nl", "platform": "desktop" }, "checkin": "2026-10-02", "checkout": "2026-10-05", "city": -2140479, "guests": { "number_of_adults": 2 }, "page": "eyJhbGciOiJIUzI1NiJ9.eyJwIjp7ImJvb2tlciI6eyJjb3VudHJ5IjoibmwiLCJwbGF0Zm9ybSI6ImRlc2t0b3AifSwiY2hlY2tpbiI6IjIwMjUtMTAtMDIiLCJjaGVja291dCI6IjIwMjUtMTAtMDUiLCJjaXR5IjotMjE0MDQ3OSwiZ3Vlc3RzIjp7Im51bWJlcl9vZl9hZHVsdHMiOjIsIm51bWJlcl9vZl9yb29tcyI6MX0sIm9mZnNldCI6MTAwfSwiYXVkIjoiL2FjY29tbW9kYXRpb25zL3NlYXJjaCIsImV4cCI6MTc0OTgyNTI1NH0.dg1C-3LnmS6BdGw8QZJj3NsbAcGGA7f6jYRAgpTWxsM" } ``` Response: ```json { "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: ```json { "page": "eyJhbGciOiJIUzI1NiJ9.eyJwIjp7ImJvb2tlciI6eyJjb3VudHJ5IjoibmwiLCJwbGF0Zm9ybSI6ImRlc2t0b3AifSwiY2hlY2tpbiI6IjIwMjUtMTAtMDIiLCJjaGVja291dCI6IjIwMjUtMTAtMDUiLCJjaXR5IjotMjE0MDQ3OSwiZ3Vlc3RzIjp7Im51bWJlcl9vZl9hZHVsdHMiOjIsIm51bWJlcl9vZl9yb29tcyI6MX0sIm9mZnNldCI6MTAwfSwiYXVkIjoiL2FjY29tbW9kYXRpb25zL3NlYXJjaCIsImV4cCI6MTc0OTgyNTI1NH0.dg1C-3LnmS6BdGw8QZJj3NsbAcGGA7f6jYRAgpTWxsM" } ``` #### Example 3 - Conflicting date values In this example the `checkout` date happens before the `checkin` date: ```json { "booker": { "country": "nl", "platform": "desktop" }, "checkin": "2026-10-12", "checkout": "2026-10-05", "city": -2140479, "guests": { "number_of_adults": 2 }, ``` The response: ```json { "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](/demand/docs/open-api/demand-api/). ### Expired pagination token **Description** - Returned when the pagination token is older than 3 hours. Example response: ```json { "request_id": "01gw74d6yddk07fa11g4psnfrb", "errors": [ { "id": "expired_token", "message": "Token 'page' has expired." } ] } ``` **Solution**: 1. Repeat the original request to retrieve a new `next_page` token. 2. 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, there is not more results. 3. Repeat the process until the response no longer includes a `next_page` field in the response. See the [Pagination guide](/demand/docs/development-guide/pagination) 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`. ```json curl -L -X POST 'https://demandapi-sandbox.booking.com/3.1/accommodations/availability?affiliate_id=12345' ``` The response returns the error: ```json { "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](/demand/docs/getting-started/try-out-the-api) 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](/demand/docs/open-api/demand-api/orders/orders/preview) 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](/demand/docs/open-api/demand-api/orders/orders/preview) request with children included: ```json { "booker": { ... }, "currency": "EUR", "accommodation": { "id": 600455, "checkin": "2026-02-21", "checkout": "2026-02-25", "products": [ { "id": "60045504_87857366_85_0_489717", "allocation": { "number_of_adults": 1, "children": [ 8 ] } } ] } } ``` The response will return this error: ```json { "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](/demand/docs/open-api/demand-api/accommodations/accommodations/details) to identify "Adults Only" properties in advance. See the [Family use cases](/demand/docs/accommodations/occupancy-use-cases#adults-only-properties) section for guidance. ### Invalid token **Description** - Returned when the `page` token is not recognised. ```json { "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: ```json { "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: 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. 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). 3. 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`: ```json } "checkin": "2026-10-02", "checkout": "2026-10-05", "city": -2140479, "guests": { "number_of_adults": 2, "number_of_rooms": 1, "children": 2, 3, 13, 15, // [!code highlight] } } ``` The response: ```json { "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: ```json { "checkin": "2026-10-02", "checkout": "2026-10-05", "city": -2140479, "guests": { "number_of_adults": 2, "number_of_rooms": 1, "children": [2, 3, 13, 15] // [!code highlight] } } ``` #### Example 2 - Invalid date format Parameter with an invalid format for the `checkin` date: ```json { "checkin": "25-10-02", "checkout": "2026-10-05", ... } } ``` The response: ```json { "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. ```json ... "checkin": "2026-10-02", "checkout": "2026-10-05", "city": -2140479, "extras": ["products","rooms"], // [!code highlight] ``` The response: ```json { "request_id": "01gw5btwz6k3b6ajprx36hm6d4", "errors": [ { "id": "invalid_parameter", "message": "Parameter 'extras[1]' is invalid." } ] } ``` #### Example 4 - Invalid country format If the response returns this error: ```json { "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. ```json { "accommodation": 10004, "booker": { "country": "nl", "platform": "" // [!code highlight] }, "checkin": "2026-02-15", "checkout": "2026-02-18", "extras": [ "extra_charges" ], "guests": { "number_of_adults": 2, "number_of_rooms": 1 } } ``` The error response: ```json { "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. ```json { "airport": "AMS" // [!code highlight] "languages": [ "en-gb", "zh-cn" ] } ``` The response: ```json { "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) ```json { "accommodation": 10004, "booker": { "country": "nl", "platform": "desktop" }, "checkout": "2026-02-18", "extras": [ "extra_charges" ], "guests": { "number_of_adults": 2, "number_of_rooms": 1 } } ``` The error response: ```json { "request_id": "01jh2pvsgvvxb0w7wjce4smkgm", "errors": [ { "id": "missing_parameter", "message": "Parameter 'checkin' is missing." } ] } ``` **Solution**: - Add the required parameter. - Check the [API Reference](/demand/docs/open-api/demand-api/) for more details on required parameters. ### Unknown parameter **Description** - The request contains a parameter that is not recognised by the endpoint schema. **Example response**: ```json { "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](/demand/docs/open-api/demand-api/) for the list of supported parameters. ## Related topics Curious to know more? - [Authentication guide](/demand/docs/development-guide/authentication) - Make sure your requests are properly authenticated to avoid 401/403 errors. - [OpenAPI reference](/demand/docs/open-api/demand-api) - Check parameter requirements and valid combinations for each endpoint. - [Pagination guide](/demand/docs/development-guide/pagination) - Learn how to correctly use the `page` parameter and avoid conflicts with search filters. - [Order cancellation errors](/demand/docs/orders-api/cancel-order#handling-errors) - Handle client errors specific to order cancellation. - [Payment errors](/demand/docs/support/error-handling/payment-errors)- Understand client-side issues during payment flows. - [HTTP 4xx status code scenarios](/demand/docs/support/error-handling/http-4xx-scenarios) - A complete guide to 4xx status codes used by the Demand API.