# 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 or the request is not allowed in the sandbox environment.

**Common causes**:

**Authentication issues:**

* Missing or incorrect `Authentication` or `X-Affiliate-Id` headers.
* Invalid or revoked API key.


**Environment restrictions:**

* The requested endpoint is not available in the sandbox environment (for example, car rental endpoints).


**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.
* If you are calling a car-related endpoint, use the production environment instead, as these endpoints are not available in sandbox.


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.


**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](/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`


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