Errors & Retries

Unifystays returns structured errors with HTTP status codes. Every response includes an X-Request-Id header.

X-Request-Id: req_4f7b2c8e91ab4401

Include this request ID when reporting an issue.

Common Status Codes

Status	Meaning	Client action
`400`	Invalid request, validation failure, or provider rejection.	Fix the request body or show the validation message to the user.
`401`	Missing or invalid API key.	Check the `x-api-key` header.
`404`	Resource not found or expired.	Refresh the search, room, prebook, or booking state.
`409`	Conflicting booking state.	Fetch the booking again before retrying.
`429`	Rate limit reached.	Retry after the configured cooldown.
`500`	Unexpected server error.	Retry if safe, then contact support with `X-Request-Id`.
`502`	Supplier rejected or could not complete the operation.	Follow the stable error code; do not retry unless instructed.
`503`	Supplier operation failed transiently.	Retry after a short exponential backoff.

Retry Guidance

Safe to retry: GET endpoints and POST /hotels/book with the same Idempotency-Key and identical request body.
Use caution: POST /hotels/prebook, because supplier availability can change.
Do not create a new booking retry key unless the user intentionally starts a new booking attempt.

For 429 and transient 500 responses, delay the retry and increase the delay between consecutive attempts. Do not retry a failed validation request until you have corrected the input.

Expired Tokens

Room booking_token and prebooking IDs are short lived. If a token expires, restart from room availability or search.

Room Allocation and Prebook Errors

Error code	Meaning	Recovery
`BOOKING_TOKEN_HOTEL_MISMATCH`	The prebook `hotel_id` is not the hotel bound to the selected `booking_token`.	Do not retry the same pair. Return to the room state and use the hotel ID and token from the same option response.
`BOOKING_TOKEN_INVALID` or `BOOKING_TOKEN_EXPIRED`	The room token cannot be verified or is no longer valid.	Start a new room request, reconnect to its stream, and select a fresh option.
`PREBOOKING_ID_INVALID`, `PREBOOKING_ID_EXPIRED`, or `PREBOOKING_ID_ALREADY_USED`	The booking request cannot consume the supplied prebooking context.	Complete a new prebook. Do not modify or reuse the old ID.
`BOOKING_ROOM_COUNT_MISMATCH`	The booking room count differs from prebook.	Build `rooms` again from every prebook room allocation.
`BOOKING_ROOM_ALLOCATION_MISMATCH`	An allocation ID is missing, duplicated, or unknown.	Copy every prebook `room_allocation_id` exactly once. Never substitute the mapped room’s `room_id`.
`BOOKING_ROOM_OCCUPANCY_MISMATCH`	Adult or child guest counts do not match the selected room allocation.	Match guest `type` counts to that allocation’s prebook `occupancy`.

A room without a safe catalogue match is not an error. AMBIGUOUS, UNMAPPED, and CONFLICT mapping statuses have unifystays_room: null; all are supported bookable states when the option and allocation IDs are present. Render the room from provider_room instead of hiding the option.

Supplier Operation Errors

Supplier-native error strings are retained privately for support and are not a stable customer contract. Use the normalized Unifystays code and retryable value instead.

Error code	Meaning	Client action
`PROVIDER_NOT_AUTHORIZED`	Supplier credentials or permissions are invalid.	Correct the supplier connection; do not retry the same request.
`PROVIDER_RATE_LIMITED`	The supplier’s endpoint limit was reached.	Retry with backoff.
`PROVIDER_CONFIGURATION_ERROR`	Contract, endpoint, or environment configuration issue.	Correct the supplier setup; do not retry automatically.
`SUPPLIER_CREDIT_INSUFFICIENT`	Supplier account credit/balance is insufficient.	Fund or extend the supplier account before retrying.
`OFFER_UNAVAILABLE`	Rate expired, disappeared, or sold out.	Restart rooms search and select a new offer.
`CANCELLATION_REJECTED`	Supplier definitively refused cancellation.	Keep the booking active and show the supplier-safe cancellation state.
`PROVIDER_REQUEST_FAILED`	Supplier failure not covered by a narrower code.	Retry only when the response explicitly says it is retryable.

For an uncertain booking-creation result, Unifystays keeps the booking in PROCESSING and performs supplier status reconciliation. Do not create a new booking or change the idempotency key. For an uncertain cancellation result, the booking remains CANCELLATION_PENDING until the supplier order record confirms its state.

Search Refreshes

Poll GET /hotels/search/{searchId}/prices every 2 seconds only while the customer is viewing a search result page.
Stop polling when the refresh status is COMPLETE or EXPIRED.
Use refresh_ids to prioritize hotel cards currently visible to the customer.

See Caching Strategy for cache lifetime and request volume guidance.

Get started

Build your integration

Operate

Common Status Codes

Retry Guidance

Expired Tokens

Room Allocation and Prebook Errors

Supplier Operation Errors

Search Refreshes

​Common Status Codes

​Retry Guidance

​Expired Tokens

​Room Allocation and Prebook Errors

​Supplier Operation Errors

​Search Refreshes

Common Status Codes

Retry Guidance

Expired Tokens

Room Allocation and Prebook Errors

Supplier Operation Errors

Search Refreshes