# 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](/demand/docs/support/error-handling/about-errors#common-http-status-codes).

## Common HTTP 4xx error scenarios

### 400 - Bad request

**Description** - The request is malformed or contains missing/invalid parameters.

Example of bad request:


```json
{
  "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](/demand/docs/support/error-handling/error-codes).

### 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 every request.
* Regenerate the API key if needed.


See the [Authentication guide](/demand/docs/development-guide/authentication) 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.
* (Car rentals only) The endpoint is not available in the sandbox environment.


**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.
* If using the Cars API, ensure you are using the production environment, as Cars endpoints are not available in sandbox.


### 404 - Not found

**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](/demand/docs/open-api/demand-api/) 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](/demand/docs/open-api/demand-api/) 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:


```json
{
  "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](/demand/docs/orders-api/cancel-order) for valid scenarios.

**Scenario 2 – Product is no longer available**

When the order has an unavailable item:


```json
{
  "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](/demand/docs/open-api/demand-api/orders/orders/preview) and [orders/create](/demand/docs/open-api/demand-api/orders/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**

1. Recheck product availability via the [/accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) endpoint to refresh the current status of the products.
2. If the specific product is confirmed as unavailable, allow the traveller to select an alternative product or accommodation.
3. 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.


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


```json
{
  "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.


### 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:


```json
{
  "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`


### 422 - Unprocessable content

**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:


```json
{
  "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](/demand/docs/support/error-handling/payment-errors) for detailed payment-related error scenarios.

### 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](/demand/docs/development-guide/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.

## Related topics

Curious to know more?
- [Payment errors](/demand/docs/support/error-handling/payment-errors)- Understand client-side issues during payment flows.
- [Client error codes and examples](/demand/docs/support/error-handling/error-codes) - A complete guide to client error codes used by the Demand API.
- [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.