Errors

HTTP Errors

Our API follows a predictable HTTP error code format:

400 - Bad Request: The request cannot be processed
401 - Unauthorized: The API key token is missing, invalid, or expired.
403 - Forbidden: The API key token cannot access the specified resource.
404 - Not Found: The request resource cannot be found.
500 - Internal Server Error: Failure to process the request.

Error Structure

Errors are always returned in JSON format. Each error includes a code and a message, indicating the general reason for the error, as well as a type to categorize the issue. Additionally, a details array provides more specific information about the error condition. For example:

{
    "code": 2001,
    "details": [
        {
            "message": "check_in_date is not less than check_out_date. Please check reservation dates."
        }
    ],
    "message": "Unable to process your request. Missing or invalid request parameters.",
    "request_id": "9a15bee6-43c7-40b1-8b52-dd28daf9134b",
    "type": "VALIDATION"
}

Detailed Error Codes List

Application Error

Code	HTTP Status	Message	Corrective Action
1002	500 Internal Server Error	Unable to process the payment.	Retry the request. If the problem persists, contact Selfbook support.
1004	400 Bad Request	Rate validation failure	Refresh the rate by re-running rate verification before submitting the reservation.
1005	400 Bad Request	Rate validation failure	Ensure `rate.price.base_price`, `total_taxes`, and `total_price` in the create request match the values returned by rate verification.
1006	500 Internal Server Error	An internal error has occurred.	Retry the request. If the error persists, contact Selfbook support.

Validation

Code	HTTP Status	Message	Corrective Action
2001	400 Bad Request	Unable to process your request. Missing or invalid request parameters.	Review the `details` array in the response for the specific field(s) that failed validation and correct them before retrying.
2002	400 Bad Request	Unable to process the payment.	Re-tokenize the guest payment method and retry with new token.
2003	400 Bad Request	Unable to make requested modification.	Check the modification rules for this reservation (e.g. rate policy, check-in window) and adjust the request accordingly.
2005	400 Bad Request	Missing TripAdvisor IDs	Verify the TripAdvisor IDs supplied are valid and mapped to properties in the Selfbook catalog.
2009	400 Bad Request	Unable to process your request. The custom_data object has errors.	Review the `details` array for specific `custom_data` field errors and correct them.
2010	400 Bad Request	This reservation is non-cancellable.	This reservation cannot be cancelled. The rate is non-refundable. No further action is possible via the API.
2010	400 Bad Request	Invalid coordinates or radius	Provide valid `latitude` and `longitude` values in decimal degree format.
2011	400 Bad Request	Invalid search radius	Set the search `radius` to a value between 0.1 and 25 kilometers.
2012	400 Bad Request	Search radius too large	Reduce the search `radius` to 25 kilometers or less.
2013	400 Bad Request	Invalid filter parameters	Review the filter combinations in your request; certain filters cannot be combined. Consult the API reference for supported combinations.
2014	400 Bad Request	Invalid pagination parameters	Ensure `page` and `page_size` are positive integers.

Payment Processing Error

Code	HTTP Status	Message	Corrective Action
3101	400 Bad Request	Unable to process the payment.	Retry the request. If the error persists, contact Selfbook support.
3102	400 Bad Request	Unable to process the payment.	Check the `details` array for the refusal reason. Ask the guest to use a different payment method or contact their card issuer.
3201	400 Bad Request	Error	Retry the request. If the error persists, contact Selfbook support.
3501	400 Bad Request	Unable to process the payment.	Verify the payment token is valid and retry. If the error persists, contact Selfbook support.
3502	400 Bad Request	Unable to process the payment.	The payment token could not be processed. Ask the guest to re-enter payment details.
3503	400 Bad Request	Unable to process the payment.	Retry the request. If the error persists, contact Selfbook support.
3504	400 Bad Request	Error	Retry the request. If the error persists, ask the guest to re-enter payment details.
3505	400 Bad Request	Error	Retry the request. If the error persists, contact Selfbook support.

Booking Creation Error

Code	HTTP Status	Message	Corrective Action
4002	400 Bad Request	Booking Exception	The booking request could not be completed. Please retry. If the error persists, contact Selfbook support.
4003	400 Bad Request	Booking Failure	Indicates the booking failed. Retry the booking request. If the error persists, contact Selfbook support.

Booking Cancellation Error

Code	HTTP Status	Message	Corrective Action
4004	400 Bad Request	Cancellation Exception	Retry the cancellation request. If the error persists, contact Selfbook support to confirm the cancellation status.
4005	400 Bad Request	Cancellation Failure	Retry the cancellation request. If the error persists, contact Selfbook support to confirm the cancellation status.

Availability Search Error

Code	HTTP Status	Message	Corrective Action
4006	400 Bad Request	Availability Search Exception	Retry the availability search.
4007	400 Bad Request	Availability Search Failure	Retry the availability search.
4008	404 Not Found	No properties found for availability search.	Verify the property identifier is correct. The property may not be available through this channel.
4107	500 Internal Server Error	Availability Search Failure	Retry the availability search. If the error persists, contact Selfbook support.

Booking Modification Error

Code	HTTP Status	Message	Corrective Action
4009	400 Bad Request	Modification Failure	Retry the modification request. If the error persists, contact Selfbook support.

Hotel Rate Verification Failure

Code	HTTP Status	Message	Corrective Action
4010	400 Bad Request	The hotel offer may have expired, or no longer exists.	Re-run availability search and rate verification to obtain a fresh offer, then retry.

Supplier Authentication Error

Code	HTTP Status	Message	Corrective Action
4011	500 Internal Server Error	Supplier Authentication failure.	Contact Selfbook support.

Hotel Offer Not Found Failure

Code	HTTP Status	Message	Corrective Action
4012	404 Not Found	The hotel offer was not found.	The offer has expired or does not exist. Re-run availability search to obtain a new offer.

Supplier Connection Error

Code	HTTP Status	Message	Corrective Action
4030	502 Bad Gateway	Unable to reach service.	Retry. If the error persists, contact Selfbook support.

Not Found Error

Code	HTTP Status	Message	Corrective Action
4040	404 Not Found	The requested resource could not be found	Verify the resource ID in your request is correct.

Get Started

Search Use Cases

Booking Use Cases

Reservation Modification Use Cases

API Documentation

Webhooks

API Reference

Postman

Changelog

HTTP Errors

Error Structure

Detailed Error Codes List

Application Error

Validation

Payment Processing Error

Booking Creation Error

Booking Cancellation Error

Availability Search Error

Booking Modification Error

Hotel Rate Verification Failure

Supplier Authentication Error

Hotel Offer Not Found Failure

Supplier Connection Error

Not Found Error

​HTTP Errors

​Error Structure

​Detailed Error Codes List

​Application Error

​Validation

​Payment Processing Error

​Booking Creation Error

​Booking Cancellation Error

​Availability Search Error

​Booking Modification Error

​Hotel Rate Verification Failure

​Supplier Authentication Error

​Hotel Offer Not Found Failure

​Supplier Connection Error

​Not Found Error

HTTP Errors

Error Structure

Detailed Error Codes List

Application Error

Validation

Payment Processing Error

Booking Creation Error

Booking Cancellation Error

Availability Search Error

Booking Modification Error

Hotel Rate Verification Failure

Supplier Authentication Error

Hotel Offer Not Found Failure

Supplier Connection Error

Not Found Error