Hotel errors
You interpret stable error codes and reasons to choose a safe next action.
You receive hotel service errors in a JSON envelope with a stable code, an optional reason, a human-readable message and a request_id. You branch on code and reason; message and details are diagnostic text and can change. The gateway can return its own error envelope before a service response reaches you, so you also handle the gateway errors described below.
{
"error": {
"code": "internal_error",
"reason": "result_unknown",
"message": "Hotel booking result is unknown",
"request_id": "req_example"
}
}| HTTP status / code | Your next action |
|---|---|
| 400 / validation_error | Correct the request shape, headers, party or field values. |
| 401 / unauthorized | Check the authentication required by the endpoint you called. |
| 404 / not_found | Check the resource ID and booking owner; another owner's booking is also hidden as not found. |
| 409 / conflict | Read the booking's current state before deciding whether this operation is allowed. |
| 422 / unprocessable | Use reason to correct the request or choose another offer; do not blindly retry. |
| 502 / supplier_unavailable | Your supplier read failed. Repeat read operations with bounded backoff. |
| 503 / supplier_unavailable | Your supplier is limiting how often it can be called. Repeat the read after a short wait. |
| 500 / internal_error | Read the existing booking after a mutation; do not assume the supplier refused. Contact support with request_id. |
Handle gateway errors
You can receive a gateway error with error.code and error.message but no hotel reason or request_id. The gateway can also forward a hotel error unchanged, so the HTTP status alone does not identify which envelope you received.
| Gateway code | Your next action |
|---|---|
| UnauthenticatedError | Check your API key; the gateway did not authenticate this request. |
| PlatformUnavailableError | Wait before retrying authentication; do not replace a valid key because credential verification was unavailable. |
| BadGatewayError | Repeat a read with bounded backoff; after a mutation, recover its stored outcome because a gateway failure does not establish whether the service acted. |
| ServiceUnavailableError | Repeat a read with bounded backoff; after a mutation, recover its stored outcome because the service may have acted before the gateway timed out. |
| internal_error | Recover the stored outcome after a mutation and contact support if it remains unresolved. |
You recover prebook with the same idempotency key and read the existing booking after book or cancel. You retain any response request ID that is present, along with your booking ID and the time of the request, for support. A missing hotel reason is not permission to create a replacement purchase.
Interpret the reason
| Reason | Your next action |
|---|---|
| offer_expired | Obtain a fresh offer when the prior booking is safe to replace. |
| cursor_expired | Search again from the first page; your cursor is too old, or its supplier no longer serves the search. |
| price_changed | Obtain and review a fresh price before proceeding. |
| guest_mismatch | Check names, room order and occupancy against the priced party. |
| stay_changed | Obtain an offer for the intended hotel and travel dates. |
| cancellation_restricted | Review the policy window before requesting cancellation again. |
| geo_required | Supply a geographic destination with coordinates and a radius; for booking weather, contact support when the stored hotel coordinates are missing. |
| city_required | Supply a city and country for your destination. |
| manual_review_required | Contact support; do not automate another mutation. |
| payment_method_unsupported | Choose an offer with a supported payment method. |
| cancellation_policy_unsupported | Choose another offer; its terms cannot be represented safely. |
| cancellation_not_quotable | Do not promise a fee or refund; seek assistance with the cancellation terms. |
| refund_not_cash | Choose another offer; the supplier's refund method is unsupported. |
| payment_failed | Check your payment authorization and booking state before proceeding. |
| supplier_operation_unsupported | Select a configured supplier that supports this operation. |
| booking_incomplete | Contact support about missing stored booking or payment details. |
| supplier_rejected | Review the refusal and choose a valid alternative after resolving the original booking. |
| loyalty_membership_rejected | The supplier refused the loyalty membership (an invalid number or an unaccepted programme), or the rate requires a membership that cannot be submitted with it. Search again with a corrected number, without the membership, or for a non-member offer. |
| supplier_unreachable | Repeat a read with bounded backoff; this reason is not proof that a purchase failed. |
| supplier_rate_limited | Wait before repeating the read and use bounded backoff; limits vary by supplier and operation. |
| result_unknown | Read the same booking and seek support if unresolved; do not purchase again. |
You retain the booking ID, operation and request_id for support. You keep payment tokens, offer references, ingress secrets and guest details out of diagnostic messages.