Client-side errors (HTTP 4xx) indicate that the request sent to the Demand API is invalid. This page describes common 4xx errors, explains their causes, and offers example responses and recommended solutions.
Client-side errors in the Demand API occur when a request is invalid due to incorrect formatting, missing or unsupported parameters, or authentication issues.
Use the examples and guidance below to troubleshoot and resolve these errors efficiently.
Need a quick summary? See the Common HTTP status codes table.
Description - The request is malformed or contains missing/invalid parameters.
Example of bad request:
{
"request_id": "01gw5aaj8dkh7fvgwa7phs916x",
"errors": [
{
"id": "missing_parameter",
"message": "Parameter 'checkin' is missing."
}
]
}
Solution: Review the request format, parameter values, and ensure all required parameters are included.
Refer to the Client error codes examples.
Description - Authentication has failed.
Common causes:
- Missing or incorrect
AuthenticationorX-Affiliate-Idheaders. - Invalid or revoked API key.
Solution:
- Ensure the
Authenticationand/orX-Affiliate-Idheaders are correct, up to date, and included in every request. - Regenerate the API key if needed.
See the Authentication guide for correct setup.
Description - Access to the requested resource is denied.
Common causes:
- Incorrect or unrecognised affiliate ID.
- Insufficient permissions to access the endpoint.
- (Car rentals only) The endpoint is not available in the sandbox environment.
Solution:
- Check that the
X-Affiliate-Idheader uses the correct ID. - If access is restricted, contact your Booking.com Account Manager to request permission.
- If using the Cars API, ensure you are using the production environment, as Cars endpoints are not available in sandbox.
Description - The requested endpoint does not exist, is unavailable in the current environment, or is not supported for the requested product.
Common causes:
- Typo or incorrect endpoint URL.
- The endpoint is unavailable or has been deprecated.
Solution
- Double-check the request URL.
- Refer to the API Reference for valid endpoint paths.
Description:
- The HTTP method used is not allowed for the requested endpoint.
- Only POST requests are supported across all Demand API v3.x endpoints.
Solution:
- Ensure the request uses the POST method with a properly structured JSON body.
- Refer to the API Reference for further details.
Description:
- The request did not specify a valid Accept header.
- The Demand API only returns responses in application/json format.
Solution:
- Set this header in your request:
Accept: application/json
Description - A conflict occurred during order creation or cancellation.
Scenario 1 – Attempting to cancel an invalid order
When trying to cancel an order without "Booked" status, this message appears:
{
"id": "order_unavailable",
"message": "The order cannot be cancelled due to its current state (e.g. stayed)."
}Solution:
- Only orders in a valid state (e.g. "booked") can be cancelled.
See the Order cancellations guide for valid scenarios.
Scenario 2 – Product is no longer available
When the order has an unavailable item:
{
"id": "order_unavailable",
"message": "Order has unavailable items: product '1050736003_377312697_0_2_9' for this order is unavailable."
}The response identifies that the product included in the order (with id 1050736003_377312697_0_2_9) is no longer available at the time of the request.
This typically occurs during the orders/preview and orders/create process when the availability of a product changes after it was initially selected.
Common causes:
- Outdated storage: You may be relying on stored availability data that does not reflect the current real-time status of the product.
- Race conditions: Availability may have changed between the time the user searched for the accommodation and the time the order was submitted.
Solution
- Recheck product availability via the /accommodations/availability endpoint to refresh the current status of the products.
- If the specific product is confirmed as unavailable, allow the traveller to select an alternative product or accommodation.
- Manual filtering: If a product is returned in availability search but fails during creation, another alternative is manually removing this product from your data store, so it is not retrieved in results.
Avoid relying solely on stored availability data. Consider hiding unavailable products from your user interface.
Scenario 3 – The order is duplicated (for car rentals only)
When this error is returned with a reservation ID, it indicates that the orders/create request was already successfully processed previously, and the reservation already exists.
{
"id": "duplicate_request",
"message": "This reservation already exists for the submitted request. Use the returned reservation ID to retrieve the booking via /orders/details and check its status (booked or processed). Do not retry the request."
"reservation": "982045031"
}Common causes:
- The same request is submitted multiple times (e.g. due to timeouts or retries)
- A previous response was not received, but the booking was still created successfully.
Solution
- Treat this response as a successful, idempotent outcome, not a failure.
- Use the returned reservation ID to retrieve the existing booking details via the relevant endpoint (for example, /orders/details).
- Do not retry the same request, as this may continue to return the same error.
Description - The request format is not supported or the body request is missing.
Common causes
- The
Content-Typeheader is missing or does not include JSON as an acceptable format for the request.
Invalid example: Content-Type: text/plain
Example response:
{
"request_id": "01gw7xk69ajh4z7x2dzgyjzwwz",
"errors": [
{
"id": "unsupported_media_type",
"message": "Unsupported media type. Please use 'application/json'."
}
]
}Solution:
- Ensure your request includes this header:
Content-Type: application/json
Description - The request is syntactically valid, but the server cannot process it due to business or validation rules.
- This status code is commonly returned for payment-related failures during order creation.
Common causes
- Payment authorisation failed.
- The selected payment method is invalid or unsupported.
- Strong Customer Authentication (SCA) validation failed.
- The card has insufficient funds or exceeded transaction limits.
- The card was blocked, expired, or reported as lost.
Example response:
{
"request_id": "01gw7p7mp43dccs5zje3gezwkc",
"errors": [
{
"id": "payment_refused_insufficient_funds",
"message": "Payment could not be processed: There is insufficient funds on the credit card used to book."
}
]
}Solution:
- Review the error response details to identify the specific validation or payment failure.
- Ensure payment details and authentication data are correct.
- Retry using a valid payment method if necessary.
See the Payment refused errors guide for detailed payment-related error scenarios.
Description - The rate limit has been exceeded.
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:
- Implement exponential backoff (e.g. wait 1, 2, 4, 8, 16 seconds between retries).
- If the issue persists after the retry limit is reached, stop retrying and contact Booking.com for assistance.
Avoid retrying immediately or with a fixed delay.
- Payment errors- Understand client-side issues during payment flows.
- Client error codes and examples - A complete guide to client error codes used by the Demand API.
- 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
pageparameter and avoid conflicts with search filters. - Order cancellation errors - Handle client errors specific to order cancellation.