Errors & Retries

Handle error responses, request IDs, throttling, and safe 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.

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.

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.