SUPPORT
/
Error handling
/
HTTP 4xx scenarios
Last updated

HTTP 4xx error scenarios

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.

Overview

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.

Common HTTP 4xx error scenarios

400 - Bad request

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.

401 - Unauthorised

Description - Authentication has failed.

Common causes:

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

Solution:

  • Ensure the Authentication and/or X-Affiliate_Id headers are correct, up to date and included in each of the endpoints requests.
  • Regenerate the API key if needed.

See the Authentication guide for correct setup.

403 - Forbidden

Description - Access to the requested resource is denied.

Common causes:

  • Incorrect or unrecognised affiliate ID.
  • Insufficient permissions to access the endpoint.

Solution:

  • Check that the X-Affiliate_id header uses the correct ID.
  • If access is restricted, contact your Booking.com Account Manager to request permission.

404 - Not found

Description - The requested endpoint or resource does not exist.

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.

405 - Method not allowed

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.

406 - Not acceptable

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

409 - Conflict

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 with id 1050736003_377312697_0_2_9 is no longer available.

Solution If a product is no longer available, in orders/preview or orders/create:

  1. Recheck product availability via the [/accommodations/availability](accommodation/availability endpoint.
  2. Select an alternative product.
Important

Avoid relying solely on cached availability data. Consider hiding unavailable products from your user interface.

415 - Unsupported media type

Description - The request format is not supported or the body request is missing.

Common causes

  • The Content-Type header 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

429 - Too many requests

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.
Important

Avoid retrying immediately or with a fixed delay.

Curious to know more?
Previous page
Next page