title: HTTP 4xx error scenarios description: "Learn about common HTTP 4xx client-side errors in the Demand API, including causes, example responses, and recommended solutions for bad requests, authentication, permissions, conflicts, and rate limiting." tags:

• error handling
• http status codes
• client errors
• bad request
• authentication
• rate limiting api:
• /accommodations/search
• /accommodations/availability
• /orders/preview
• /orders/create keywords:
• Demand API errors
• http 400 bad request
• http 401 unauthorised
• http 403 forbidden
• http 404 not found
• http 405 method not allowed
• http 406 not acceptable
• http 409 conflict
• http 415 unsupported media type
• http 429 too many requests x-redocly: seo: title: "Demand API v3.1 – HTTP 4xx Error Scenarios" description: "Comprehensive guide to Demand API v3.1 HTTP 4xx client error scenarios with causes, example responses, and step-by-step solutions for invalid requests, authentication, permissions, and rate limiting." audience: [developer, partner, integrator] apiVersion: v3.1 product: [accommodation, cars, messaging, flights, attractions, demand-api]

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.

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.

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.

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.

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](accommodations/availability endpoint.
2. Select an alternative product.

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.

Related topics