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

Start with this overview to understand error types and handling strategies.
Quickly check common HTTP responses in the HTTP status mapping table or explore further examples in the HTTP dedicated section.
Explore client error codes and examples.
Consult Payment errors for transaction-specific cases.

Type of API errors

The Demand API may return two types of errors:

🌐 Network-level errors

When - Before the request reaches the server.
Symptoms - Timeouts, no response, DNS/routing issues.
Example - Request failed, 503 Service Unavailable.
How to handle - Retry with exponential backoff, check client connectivity or outages.

📡 HTTP-level errors

When - After the server processes the request
Symptoms - Response with 4xx or 5xx status and JSON error body.
Example - 400 Bad Request., 429 Too Many Requests.
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.

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 for the response schema.
400 Bad request	Client error	Request is malformed or contains invalid data.	Missing required parameter Invalid value or format Conflicting parameters Invalid or expired pagination token Request body missing Use of unsupported query parameters	Check and correct all request parameters, formats, and structure. Refer to the API reference.
401 Unauthorised	Client error	Authentication failed.	Missing/incorrect `Authentication` or `X-Affiliate-Id` headers Revoked or expired access token.	Verify credentials, header names, and values. Regenerate the API key if necessary. See Authentication guide.
403 Forbidden	Client error	Access denied.	Invalid affiliate ID Insufficient permissions for the endpoint	Correct the affiliate ID or request permission from Booking.com. See Authentication guide.
404 Not found	Client error	Endpoint does not exist.	Incorrect or deprecated URL	Verify and update the endpoint URL. Check the API reference.
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.	Ensure the order is in a cancellable state. Check product availability via `/accommodations/availability`.
415 Unsupported media type	Client error	Unsupported request format.	Incorrect or missing `Content-Type` header Unsupported charset.	Set `Content-Type: application/json` and ensure proper formatting.
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 issue Timeout System 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:

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

Client error codes & examples

HTTP 4xx error scenarios

Payment errors