# Understanding and handling API errors

**Learn how to identify and respond to errors in the Demand API, and implement best practices for building resilient, self-healing integrations.**

## Why error handling matters

When integrating with the Demand API, robust error handling is essential. This ensures your application can:

✅ Detect when a request has failed or failed to process.

✅ Respond appropriately—whether by retrying, logging, or surfacing the issue.

✅ Provide actionable feedback to users or support teams.

## How to use this documentation

1. Start with this overview to understand error types and handling strategies.
2. Quickly check common HTTP responses in the [HTTP status mapping table](/demand/docs/support/error-handling/about-errors#common-http-status-responses) or explore further examples in the [HTTP dedicated section](/demand/docs/support/error-handling/http-4xx-scenarios).
3. Explore [client error codes and examples](/demand/docs/support/error-handling/error-codes).
4. Consult [Payment errors](/demand/docs/support/error-handling/payment-errors) for transaction-specific cases.


## Type of API errors

The Demand API may return two types of errors:

div
div
h3
🌐 Network-level errors
ul
li
strong
When:
 Before the request reaches the server
li
strong
Symptoms:
 Timeouts, no response, DNS/routing issues
li
strong
Example:
code
Request failed
, 
code
503 Service Unavailable
li
strong
How to handle:
 Retry with exponential backoff, check client connectivity or outages.
div
h3
📡 HTTP-level errors
ul
li
strong
When:
 After the server processes the request
li
strong
Symptoms:
 Response with 4xx or 5xx status and JSON error body
li
strong
Example:
code
400 Bad Request
, 
code
429 Too Many Requests
li
strong
How to handle:
 Inspect error payload and message, fix client-side issues or retry when appropriate.
If you don’t receive a structured JSON error response, it’s likely a network-level issue. If you do, it’s an HTTP-level error with further detail in the errors field.

## HTTP‑level errors

The Demand API uses standard HTTP status codes to communicate request outcomes.

| Code range | Meaning |
|  --- | --- |
| 2xx | Success. |
| 4xx | Client-related issues (e.g. invalid requests, authentication failure). |
| 5xx | Server error (e.g. internal failure) |


See RFC 2616 and RFC 6585 for details.

### Common HTTP status codes

For a quick overview of most common HTTP responses returned by the Demand API, causes, and solutions, see the table below.

For more details and examples, refer to [HTTP 4xx error scenarios section](/demand/docs/support/error-handling/http-4xx-scenarios).

| Status | Type | Description | Common causes | Recommended solution |
|  --- | --- | --- | --- | --- |
| **200 OK** | Success | Request succeeded and the response contains the expected data. | — | No action needed.* Refer to the [API reference](/demand/docs/open-api/3.2/demand-api) for the response schema.

 |
| **400 Bad request** | Client error | Request is malformed or contains invalid data. | Missing required parameterInvalid value or formatConflicting parametersInvalid or expired pagination tokenRequest body missingUse of unsupported query parameters | Check and correct all request parameters, formats, and structure.* Refer to the [API reference](/demand/docs/open-api/3.2/demand-api).

 |
| **401 Unauthorised** | Client error | Authentication failed. | Missing/incorrect `Authentication` or `X-Affiliate-Id` headersRevoked or expired access token. | Verify credentials, header names, and values. Regenerate the API key if necessary.* See [Authentication guide](/demand/docs/development-guide/authentication).

 |
| **403 Forbidden** | Client error | Access denied. | Invalid affiliate IDInsufficient permissions for the endpoint | Correct the affiliate ID or request permission from Booking.com.* See [Authentication guide](/demand/docs/development-guide/authentication).

 |
| **404 Not found** | Client error | Endpoint does not exist or cannot be used in selected environment. | Incorrect or deprecated URL | Verify and update the endpoint URL or change environment. |
| **405 Method not allowed** | Client error | Unsupported HTTP method. | Using a method other than `POST` | Update the request to use the `POST` method only. |
| **406 Not acceptable** | Client error | Client did not indicate it accepts `application/json`. | Missing or incorrect `Accept` header | Set `Accept: application/json` in the request header. |
| **409 Conflict** | Client error | Order-related conflict. | * Trying to cancel a non-booked Order
* Unavailable product in the order.
* Duplicated order.

 | * Use orders/details to check the order state.
* Check product availability via/accommodations/availability.

 |
| **415 Unsupported media type** | Client error | Unsupported request format. | Incorrect or missing `Content-Type` headerUnsupported charset. | Set `Content-Type: application/json` and ensure proper formatting. |
| **422 Unprocessable content** | Client error | All sort of payment failures | Expired card, invalid payment methods, card lost, etc | See the [Payment errors guide](/demand/docs/support/error-handling/payment-errors) for details. |
| **429 Too many requests** | Client error | Rate limit exceeded. | Excessive request volume in a short period | Implement exponential backoff with a retry limit. Contact Booking.com if the issue persists. |
| **5xx Server errors** | Server error | Internal or temporary service failure. | Backend processing issueTimeoutSystem outage. | Retry with exponential backoff.* Contact your Booking.com Account Manager if the issue persists.

 |


## Error response structure

In the event of a 4xx or 5xx error, the response body adheres to the following structure:


```json
{
  "request_id": "...",
  "errors": [
    {
      "id": "specific_error_code",
      "message": "Detailed error description with suggested solution."
    }
  ]
}
```

### Key fields

|  Field | Description |
|  --- | --- |
| `errors.id` | A machine-readable error code (example: `missing_parameter`)* It replaces the deprecated `error.code` or `error.name` (in V2).
* This error code is useful for support teams and correlation.
(See the [client error codes guide](/demand/docs/support/error-handling/error-codes) for examples).

 |
| `errors.message ` | A human-readable explanation plus suggested solutions. |


## Best practices for handling and preventing errors

✅ **Implement retry strategy**

* Implement exponential backoff for 5xx and 429 errors - Include increasing intervals (e.g. 1 s, 2 s, 4 s) and a capped retry count.
* Stop retrying after a reasonable number of attempts.
* Avoid retrying client-side errors (4xx).


Important
Avoid rapid or flat retries without delay. This can intensify backend load and worsen network instability.

✅ **Logging and debugging**

* Use the `request_id` for debugging and support — this helps trace issues in logs.


✅ **Monitor error spikes and set up alerts.**

* If retries fail, alert the user or trigger an escalation process.
* If unresolved, contact your Account Manager for assistance.


✅ **Check the message**

* Always check the `message` field for details on the error and affected parameter.


✅ Fix one error at a time — the API only returns the first issue it encounters.

## What’s next?

Explore specific errors and examples.