{
"errors": ["Reservation with status TO_BE_DELIVERED cannot be cancelled"],
"error_codes": [ { "code": "NON_CANCELLABLE", "message": "Reservation with status TO_BE_DELIVERED cannot be cancelled" } ]
}
Field
Meaning
errorsDeprecated.
Human-readable messages. Always present. Log them, but don't match on their text. Kept for backwards compatibility; it will be removed in a future API version since future API versions will use structured errors.
error_codes
Machine-readable codes. Only present for some errors. It can be null or missing, especially for request validation errors. In those cases, use the HTTP status.
Two exceptions
401 Unauthorized (missing or invalid API key):
{ "message": "Api key does not exist or is invalid",
"error_codes": [ { "code": "UNAUTHORIZED", "message": "Api key does not exist or is invalid" } ] }
A malformed header (not Bearer <key>) gives the message Authorization header is invalid.
429 Too Many Requests (rate limit):
{ "error": "request limit reached" }
HTTP status codes
Status
Meaning
Retry?
200 / 201
OK / created
—
202
Accepted, no body (offer refresh)
—
204
Accepted, no body (cancellation submitted)
—
400
The request is invalid: bad parameters, failed validation, or the action isn't allowed in the current state
No. Fix the request.
401
Missing or invalid API key
No
404
Not found, or an offer expired / no longer available
No. Search again for offers.
422
The body couldn't be parsed (Invalid Body Supplied), e.g. a field has the wrong JSON type, or the action can't be processed
No. Fix the request.
429
Rate limit (500 requests/second per API key)
Yes, after a short back-off
500
Error on Katanox's side
Yes, with back-off. For bookings, check GET /bookings/{id} first if you got an ID.
505
You called /v1, which is no longer supported
No
A 2xx on POST /bookings or DELETE (cancel) doesn't mean the hotel accepted it. Like booking creation, you need to check the reservation's status and errors by calling GET /bookings/{id}: see Booking and Cancellation.
