Errors & Retries

Every error uses the same JSON envelope and a stable error.code. Branch on the HTTP status and error.code. Show your own guest-friendly message; the message text is English for logs and support and can change.

The error envelope

{
  "contract_version": "2",
  "success": false,
  "request_id": "req_4f7b2c8e91ab4401",
  "error": {
    "code": "BOOKING_TOKEN_EXPIRED",
    "message": "booking_token expired",
    "details": {}
  }
}

Field	What it means	How to use it
`success`	Always `false` for an error.
`request_id`	The ID of this request. It matches the `X-Request-Id` response header.	Log it for every failed call and quote it to support. You can send your own `X-Request-Id` (6 to 64 characters: letters, digits, `.`, `_`, `-`).
`error.code`	Stable, upper-case machine code.	Branch on it. New codes can be added; treat an unknown code like its HTTP status class.
`error.message`	Human-readable English text.	Log it. Do not parse it and do not show it to guests.
`error.details`	Extra data for some errors, or the list of validation messages.	Optional. For supplier errors it includes `retryable` (see Supplier errors).
`contract_version`	The response contract (`"2"`). Present only on `/hotels/...` calls.	Informational.

Every response, successful or not, carries an X-Request-Id header. Validation failures (400) use code VALIDATION_ERROR and list the problems in message and details.

Status codes at a glance

Status	Meaning	Client action
`400`	Invalid request, or a token or ID that cannot be used.	Fix the request, or restart the step named in the code. Do not retry unchanged.
`401`	Missing, invalid or conflicting credentials.	Check `x-api-key` and the environment.
`402`	API access is not active for your organization.	Contact support.
`403`	Key belongs to another environment, organization suspended, or not authorized for a supplier.	Fix the key or setup; contact support.
`404`	Unknown or expired resource.	Refresh the state named in the code.
`406`	The requested `X-Unifystays-Contract-Version` is not served.	Send `2` or omit the header.
`409`	The request conflicts with the current state (offer gone, booking not in the right status, idempotency conflict).	Read the code. Fetch the current state before retrying.
`422`	The request is well formed but breaks a supplier rule (guest names, missing setup).	Fix the data or setup and resend.
`424`	A supplier connection needs attention.	Contact support with the `request_id`.
`429`	Rate limit reached, or the supplier is rate limiting.	Wait for `Retry-After`, then retry with backoff.
`500`	Unexpected server error.	Retry only safe requests; contact support with `request_id`.
`501`	The supplier does not offer this operation through the API.	Do not retry. Do not offer the action.
`502`	The supplier rejected or could not complete the operation.	Follow the code; retry only if `details.retryable` is `true`.
`503`	Temporary failure (supplier or an unavailable exchange rate).	Retry with exponential backoff.

Authentication, access and rate limits

HTTP	Code	Meaning	What to do	Retry?
401	`MISSING_API_KEY`	No `x-api-key` header.	Send the header.	No
401	`INVALID_API_KEY`	The key is unknown or revoked.	Check the key and rotate it in the portal if needed.	No
401	`INVALID_AUTHENTICATION`	Conflicting credentials were sent.	Send only `x-api-key`.	No
402	`SUBSCRIPTION_REQUIRED`, `SUBSCRIPTION_EXPIRED`, `BETA_ACCESS_ENDED`	API access is not active for your organization.	Contact support.	No
403	`API_ENVIRONMENT_MISMATCH`	A Sandbox key was used on Production, or the other way round.	Use the key and base URL of the same environment.	No
403	`ORG_SUSPENDED`	Your organization is suspended.	Contact support.	No
429	`RATE_LIMITED`	You exceeded your per-key request limit.	Wait `Retry-After` seconds, then retry with backoff.	Yes, after the delay
429	`MONTHLY_LIMIT_REACHED`	Your plan’s monthly allowance is used up (Free plan only; paid plans bill overage).	Upgrade in the portal, or wait for the billing period to reset. `Retry-After` gives the seconds until it does.	After the reset
503	`API_ENVIRONMENT_UNCONFIGURED`	The environment is not available.	Retry shortly; contact support if it persists.	Yes

Each response to an authenticated request carries RateLimit-Limit and RateLimit-Remaining headers. See Rate limits.

Hotel API errors

Request, hotel and contract

HTTP	Code	Meaning	What to do	Retry?
400	`VALIDATION_ERROR`	Bad body or query, unknown field, invalid cursor, missing or invalid booking answers, no or several lead guests, duplicate guest ID, missing traveler IP for a supplier that needs it, or `language` that differs from the room search.	Read `message`, fix the request and resend.	After fixing
404	`HOTEL_NOT_FOUND`	Used for a `404` that has no more specific code: unknown hotel, unknown place, or an unknown or expired `search_id`.	Check the ID. If you were polling prices, search again.	No
406	`CONTRACT_VERSION_UNSUPPORTED`	The `X-Unifystays-Contract-Version` value is not served. `details.supported_versions` lists what is.	Send `2` or omit the header.	After fixing
500	`INTERNAL_ERROR`	Unexpected failure.	Retry once for reads. Contact support with the `request_id` if it persists.	Reads: yes. Bookings: look up first

Rooms and the room stream

HTTP	Code	Meaning	What to do	Retry?
404	`ROOM_STREAM_NOT_FOUND`	The stream does not exist or expired (about 2 minutes after `done`).	Start a new rooms search.	No (new search)
404	`ROOM_STREAM_HOTEL_MISMATCH`	The stream belongs to another hotel.	Use the `hotel_id` you searched.	No
409	`ROOM_STREAM_REPLAY_GAP`	The event you resume after is no longer retained.	Start a new rooms search.	No (new search)
409	`HOTEL_MAPPING_UNVERIFIED`, `HOTEL_MAPPING_CHECK_PENDING`	The supplier’s listing could not be verified (or is still being verified) for this hotel.	Offer another room option. For `PENDING` (`details.retryable` is `true`), retry after a few seconds.	`PENDING`: yes

Booking token and prebook

HTTP	Code	Meaning	What to do	Retry?
400	`BOOKING_TOKEN_INVALID`, `BOOKING_TOKEN_EXPIRED`, `BOOKING_TOKEN_CONTEXT_NOT_FOUND`, `BOOKING_TOKEN_OPTION_NOT_FOUND`	The token is malformed, expired or unknown (tokens last at most 15 minutes).	Run a new rooms search, reconnect to its stream and pick a fresh offer.	No (new search)
400	`BOOKING_TOKEN_HOTEL_MISMATCH`	`hotel_id` is not the hotel the token was issued for.	Send the `hotel_id` and `booking_token` from the same room request.	After fixing
409	`PREBOOK_IN_PROGRESS`	The same token is already being prebooked. Has a `Retry-After` header (3 seconds).	Wait, then repeat the identical request. Never run parallel prebooks.	Yes, same request
409	`OFFER_UNAVAILABLE`	The supplier says the offer is gone or sold out.	Run a new rooms search.	No (new search)
409	`PROVIDER_OPERATION_NOT_SUPPORTED`	The refreshed offer needs a payment method that is not supported.	Offer another room option.	No
409	`PREBOOKING_ID_EXPIRED`	The supplier’s prebooking session already ended.	Run rooms again and prebook the new offer.	No (new prebook)
502	`PREBOOK_FAILED`	A fresh availability check could not be completed.	Try again; offer another room if it persists.	Yes, with backoff

A prebook that finds the room sold out, or finds the supplier would book a different room, is not an HTTP error: it returns 200 with success: false, revalidation.decision: "NOT_BOOKABLE" and prebooking_id: null. See Prebook a Room.

Create booking

HTTP	Code	Meaning	What to do	Retry?
400	`IDEMPOTENCY_KEY_REQUIRED`	`Idempotency-Key` header is missing.	Send it.	After fixing
409	`IDEMPOTENCY_KEY_REUSED`	The key was already used with a different body.	Resend the original body, or use a new key for a genuinely new attempt.	No
400 / 409	`PREBOOKING_ID_INVALID`, `PREBOOKING_ID_EXPIRED`, `PREBOOKING_ID_ALREADY_USED`, `PREBOOKING_ID_CONTEXT_NOT_FOUND`	The prebooking cannot be used (unknown, expired, used, or from another organization with `403`).	Prebook again. Do not edit or reuse the old ID.	No (new prebook)
400	`ACCEPTED_OFFER_MISMATCH`	`accepted_offer_id` is not the offer of that prebook.	Send `data.offer.offer_id` from the same prebook response.	After fixing
400	`BOOKING_ROOM_COUNT_MISMATCH`	The number of rooms differs from prebook.	Rebuild `rooms` from every prebook room allocation.	After fixing
400	`BOOKING_ROOM_ALLOCATION_MISMATCH`	An allocation ID is missing, duplicated or unknown.	Copy every prebook `room_allocation_id` exactly once. Never use a room or family ID.	After fixing
400	`BOOKING_ROOM_OCCUPANCY_MISMATCH`	Guest counts, child types or dates of birth do not match the room’s occupancy.	Match guest types to `occupancy` (age 0 or 1 is `INFANT`, 2 and over is `CHILD`).	After fixing
422	`GUEST_NAME_INVALID`	A guest name breaks the supplier’s character rule. Nothing was sent to the supplier.	Apply the requirement’s `constraints.pattern` and `pattern_flags` in your form and resend.	After fixing
409	`HOLD_NOT_ALLOWED`	`HOLD` was requested but the offer does not allow it.	Book with `INSTANT`, or choose a holdable offer.	No
403	`PROVIDER_NOT_AUTHORIZED`	Your organization is not set up for this supplier.	Fix the setup in the portal or contact support.	No
422	`PROVIDER_CONFIGURATION_ERROR`	A setup item is missing, for example a booking contact the supplier needs.	Complete it in the portal settings.	After fixing
400	`BOOKING_CREATE_FAILED`	Unexpected failure while saving the booking.	Look the booking up by idempotency key before trying again.	After lookup
501	`PROVIDER_OPERATION_NOT_SUPPORTED`	The supplier cannot be booked through the API.	Offer another room option.	No

A request that fails validation creates nothing and does not use up the prebooking_id, so you can fix the body and resend with the same Idempotency-Key.

Confirm hold

HTTP	Code	Meaning	What to do	Retry?
409	`HOLD_CONFIRMATION_REJECTED`	The supplier definitively refused the confirmation. The booking is still `ON_HOLD`.	Treat the confirmation as failed. You may confirm again before `hold_deadline_at`, or cancel.	After fixing the cause
409	`HOLD_DEADLINE_EXPIRED`	The hold deadline has passed.	Check the status. Create a new booking if the guest still wants the room.	No
409	`HOLD_CONFIRMATION_FAILED`	The hold has no supplier reference yet.	Read the booking again; contact support if it persists.	Yes, after a pause
409	`HOLD_NOT_ALLOWED`, `ACCEPTED_OFFER_MISMATCH`	The booking is not an active hold, or the offer ID is not the booking’s.	Read the booking and resend with its `accepted_offer_id`.	After fixing
501	`PROVIDER_OPERATION_NOT_SUPPORTED`	Hold confirmation is unavailable for this supplier.	Contact support.	No

An uncertain confirmation (timeout, supplier 5xx) returns 200 with status PROCESSING. Do not call confirm-hold again; it is verified automatically.

Booking lookup and cancellation

HTTP	Code	Meaning	What to do	Retry?
404	`BOOKING_NOT_FOUND`	No booking with that ID or idempotency key for your organization.	Check the ID and that you use the key that created it. By idempotency key, `404` means no booking was created, so Create Booking can be resent with the same key and body.	See left
400	`CANCELLATION_QUOTE_REQUIRED`	`cancellation_quote_id` is missing.	Get a quote first.	After fixing
409	`CANCELLATION_QUOTE_INVALID`	The quote is expired, already used, or for another booking. Also when the penalty window changed.	Request a new quote, show the new penalty, ask again.	New quote
409	`CANCELLATION_IN_PROGRESS`	The same cancellation is still being processed. Has a `Retry-After` header.	Retry after a few seconds, or poll status.	Yes
409	`CANCELLATION_REJECTED`	The supplier refused the cancellation.	Keep the booking and show its current state.	No
409	`VALIDATION_ERROR`	The booking is in a status that cannot be quoted or cancelled, or has no supplier reference.	Read the status; offer cancellation only when `available_actions` contains `CANCEL`.	No
501	`PROVIDER_OPERATION_NOT_SUPPORTED`	The supplier does not support cancellation through the API.	Do not offer cancellation.	No

Supplier errors

Supplier-native error text is kept private and is not a stable contract. Use the normalized code and error.details.retryable.

HTTP	Code	Meaning	What to do	Retry?
424	`PROVIDER_NOT_AUTHORIZED`	Supplier credentials or permissions are invalid.	Correct the supplier connection in the portal or contact support.	No
424 / 422	`PROVIDER_CONFIGURATION_ERROR`	Contract, endpoint or environment setup issue.	Correct the supplier setup.	No
429	`PROVIDER_RATE_LIMITED`	The supplier’s own limit was reached.	Retry with backoff.	Yes
502 / 503	`SUPPLIER_CREDIT_INSUFFICIENT`	Supplier account credit is insufficient.	Fund or extend the supplier account.	After fixing
409	`OFFER_UNAVAILABLE`	Rate expired, disappeared or sold out.	Restart rooms and choose a new offer.	No (new search)
409	`CANCELLATION_REJECTED`	Supplier refused a cancellation.	See above.	No
502 / 503	`PROVIDER_REQUEST_FAILED`	Supplier failure not covered by a narrower code. `503` when temporary.	Retry with backoff only if `details.retryable` is `true`.	If `retryable`
404	`PROVIDER_MAPPING_NOT_FOUND`	No active supplier listing exists for the hotel of this booking.	Contact support with the `booking_id`.	No

Failure codes on a booking

A booking that ends FAILED carries a failure.code in Get Booking Details (and failure_code in booking.failed webhooks and list rows). It uses the same vocabulary, plus these codes:

Code	Meaning	What to do
`BOOKING_REVIEW_REJECTED`	A reviewer rejected a request that was `AWAITING_REVIEW`. Nothing was reserved.	Tell the guest; restart from rooms with a new `Idempotency-Key`.
`BOOKING_REVIEW_EXPIRED`	A request waiting for submission ran out of time (for example its free-cancellation window ended) before anything was reserved.	Same as above.
`BOOKING_RECONCILIATION_REQUIRED`	The supplier’s answer was uncertain and Unifystays is checking the real outcome. The booking stays `PROCESSING`.	Do not book again. Poll, or contact support if `CONTACT_SUPPORT` is offered.
`CANCELLATION_RECONCILIATION_REQUIRED`	The cancellation answer was uncertain. The booking stays `CANCELLATION_PENDING` until the supplier record confirms.	Poll status. Do not cancel again.
`PROVIDER_BOOKING_NOT_FOUND_AFTER_RECONCILIATION`	The supplier has no record of the booking after checking.	Contact support with the `booking_id`.

The portal approval flow (BOOKING_REVIEW_INVALID and related 409 responses) is used by the Unifystays portal only. API keys cannot approve or reject a booking.

Retry guidance

Call	Safe to retry?	How
Any `GET`	Yes	Backoff on `429`, `500`, `503`.
Autocomplete, nationalities, filters, content, search	Yes	Same request. Search with a `cursor`: keep every input identical.
`POST /hotels/{hotel_id}/rooms`	Yes	Starts a new room search with a new stream.
`POST /hotels/prebook`	Yes, with care	Same token returns the stored result without asking the supplier again. `PREBOOK_IN_PROGRESS`: wait for `Retry-After`. After a temporary supplier failure the same token can be retried about 30 seconds later. For a fresh price check, get a new token.
`POST /hotels/book`	Yes, only with the same `Idempotency-Key` and the same body	If you got no answer, first call Find Booking by Idempotency-Key. Never use a new key for an uncertain retry.
`POST .../cancellation-quote`	Yes	Quotes are free to request.
`POST .../cancel`	Yes, with the same `Idempotency-Key` and quote	Never cancels twice.
`POST .../confirm-hold`	Only after a definite rejection	An uncertain outcome is resolved automatically.

Retry rules:

Use exponential backoff with jitter (for example 1, 2, 4, 8 seconds, up to about five attempts). Honour Retry-After when present.
Do not retry a 400, 401, 402, 403, 404, 406, 422 or 501 until you have changed something.
Cap retries so a guest is not left waiting. After the cap, show a recovery option (search again, contact support).
Do not retry any 4xx as a loop. A 409 means the state changed; read the state first.

Expired and used values

Value	When it stops working	What to do
`search_id`	About 5 minutes after the search (extended by price polling with `refresh_ids`).	Search again.
`stream_id`	About 2 minutes after the stream finished.	Start a new rooms search.
`booking_token`	At most 15 minutes after the offer was quoted.	Start a new rooms search.
`prebooking_id`	At `offer.lifecycle.expires_at`, and after one successful booking.	Prebook again.
`quote_id`	After 5 minutes, after use, or when the penalty changes.	Request a new quote.

Contacting support

Send the request_id (or X-Request-Id), the booking_id when you have one, and the time of the call. Do not send API keys or full guest details. See also the IDs and Tokens Cheat Sheet, Hotel Booking Flow and Caching Strategy.

Get started

Build your integration

Operate

The error envelope

Status codes at a glance

Authentication, access and rate limits

Hotel API errors

Request, hotel and contract

Rooms and the room stream

Booking token and prebook

Create booking

Confirm hold

Booking lookup and cancellation

Supplier errors

Failure codes on a booking

Retry guidance

Expired and used values

Contacting support

​The error envelope

​Status codes at a glance

​Authentication, access and rate limits

​Hotel API errors

​Request, hotel and contract

​Rooms and the room stream

​Booking token and prebook

​Create booking

​Confirm hold

​Booking lookup and cancellation

​Supplier errors

​Failure codes on a booking

​Retry guidance

​Expired and used values

​Contacting support

The error envelope

Status codes at a glance

Authentication, access and rate limits

Hotel API errors

Request, hotel and contract

Rooms and the room stream

Booking token and prebook

Create booking

Confirm hold

Booking lookup and cancellation

Supplier errors

Failure codes on a booking

Retry guidance

Expired and used values

Contacting support