> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unifystays.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```http theme={null}
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](/guides/caching-strategy) for cache lifetime and request
volume guidance.