Errors and good practice
How an error looks
A request we cannot serve answers HTTP 400 with a list of errors:
[
{ "code": 1, "message": "Missing required parameter: date_from" },
{ "code": 2, "message": "Invalid locale" }
]
The checks run in rounds and stop at the first round that fails, so fix what the list names and send again: a later round may find more. A body that does not match the schema reports its first problem only.
message is for people, and its wording can change. Build your handling on
code.
| Code | Meaning |
|---|---|
| 1 | A required query parameter is missing (locale, date_from …) |
| 2 | locale is not one of the supported languages |
| 3 | A date is not in YYYY-MM-DD form, or the dates do not make a valid range (in the past, or the end before the start). An impossible date such as 2027-02-30 is not refused: it rolls over, so validate dates yourself |
| 4 | The request body does not match the schema: a required field is missing, or a field is not one the endpoint takes |
| 5 | The search id is invalid or has expired, or the booking's dates are not the search's: search again |
| 6 | The booking could not be made. The message says why: the property has no booking module, the plan does not let you send booking requests, the room went in the meantime, or our price has moved more than 10 EUR since your search |
| 7 | Unknown property, or one you cannot sell |
| 8 | Unknown rate plan, or one not shared with you |
| 10 | The room, rate plan, party or dates cannot be booked. The message starts with Invalid accommodation ID: and names the cause (see below) |
| 11 | The booking, or one of its rooms, could not be cancelled |
| 13 | A live (not cancelled) booking with this ref_id already exists on your account. Room ref_ids are not checked |
| 15 | The currency is not the property's currency, or differs between rooms |
| 16 | The rate plan does not allow this way of booking (see booking_types) |
| 17 | The booking could not be changed (PATCH /booking) |
| 18 | Your agency account is deactivated. Sent with HTTP 403 on every call; contact Quendoo to reactivate it. Stop retrying until then |
Codes 9, 12 and 14 are reserved and not sent today: an unknown room comes back as 10, a room that cannot be cancelled as 11.
Code 10 names the cause. After Invalid accommodation ID: the message
is one of:
That room has no availability for these dates.That rate plan is closed for that room on 2027-07-21.(orThat rate plan is closed on 2027-07-21.)That rate plan has no price for that room on 2027-07-21.The stay does not meet the rate plan's restriction 'min_los' on 2027-07-19.That rate plan is not active for these dates.(orThat rate plan is not active on 2027-07-21.)That rate plan cannot be booked today.The hotel does not sell that room to 4 adults on that rate plan.The accommodation for 4 adults is switched off on that rate plan.That room is not sold to 4 adults and 1 child aged 10 on that rate plan for these dates.(the party: the room cannot take it, or the search did not offer the room and plan for it)
On POST /booking code 10 also covers an accommodation id the search did not
offer, an extra service that was not in the offer, and an extra with no qty.
Other answers:
- 401: the token is missing, wrong or disabled. The body is
{"status": "error", "message": "errors.unauthorized"}. - 403: the credentials do not carry the scope this endpoint needs. The
body is
[{"code": 1, "message": "Missing required parameter: scope …"}]. - 403 with code 18: the token is valid, but your agency account is
deactivated. The body is
[{"code": 18, "message": "The agency account is deactivated. Contact Quendoo to reactivate it."}]. - 404: the path does not exist, or there is no booking of yours with that id. The body is empty.
- 429: too many requests. The body is
[{"code": 0, "message": "…"}]; wait a little and retry.
Retrying safely
- Reads (
GET, andPOST /search) can be repeated freely. - Bookings: always send a
ref_id. If a booking call times out, send the same request again. If the first one went through, the retry answers code 13, andGET /booking?ref_id=…gives you the booking. This holds on every booking call (/booking,with-price,request-with-price,auto-price,request-auto-price; an auto-pricedry_runbooks nothing and is not checked). A cancelled booking'sref_idcan be used again. Without aref_idyou cannot tell, and a retry can book twice. - Code 5: search again, then book. Do not retry the booking unchanged.
- Codes 6 and 10: do not retry unchanged. Read the message, then search again for what is available now.
Using the API well
- Sync in ranges. A month of prices or availability is one call, not thirty.
- Use webhooks, and keep a nightly sync as the safety net: see Webhooks.
- Search when a client is looking.
POST /searchprices live, so do not use it to crawl the calendar. That is what/rates-restrictionsand/availabilitiesare for. - Cache content.
/locations,/amenitiesand/propertieschange rarely. Refresh them daily. - Keep your token secret. It books on your account. If it leaks, disable it in your agency account and create a new one.
Rate limits: we may limit how many requests an agency sends in a minute, counted over all of its tokens. Above the limit you get HTTP 429 (see above). A full nightly sync spread over a few minutes is fine. Many refused logins from one address are also answered with 429 for a while.