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

# API reliability: errors and rate limits

> Interpret API errors, rate-limit headers, Retry-After, and X-Trace-Id in an Immoteur integration

Handle API responses from their status code and problem-details body. Do not treat a failed response as a successful result.

## Handle the response

| Outcome                | Action                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------- |
| `2xx`                  | Process the documented response body                                                              |
| `401`                  | Check the API token and Bearer authentication configuration                                       |
| `403`, `404`, or `422` | Read the `application/problem+json` response and correct access, the identifier, or request input |
| `429`                  | Wait for `Retry-After` before sending the next request, then inspect the rate-limit headers       |
| Support investigation  | Record `X-Trace-Id` with the request context                                                      |

## Read rate-limit and diagnostic headers

The rate-limit header values are ordered by second, minute, then day. Limits depend on your subscription, so read the response instead of hard-coding example values.

| Header                | Behavior                                                                   | Client action                                                               |
| --------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `RateLimit-Policy`    | Describes the active windows, for example a limit with its window duration | Use it to interpret the matching values in the remaining rate-limit headers |
| `RateLimit-Limit`     | Maximum requests in each active second, minute, and day window             | Plan throughput from the response, not from a fixed documentation value     |
| `RateLimit-Remaining` | Requests still available in each window                                    | Slow down before the smallest remaining window reaches zero                 |
| `RateLimit-Reset`     | Seconds until each current window resets                                   | Use it to decide when capacity becomes available again                      |
| `Retry-After`         | Seconds to wait after `429 Too Many Requests`                              | Do not send the next request before this delay expires                      |
| `X-Trace-Id`          | Correlation ID attached to problem responses                               | Save it with the request context when contacting Immoteur support           |

Use `curl --include` while integrating to inspect both headers and the response body:

```bash theme={null}
curl --include --show-error --silent \
  'https://api.immoteur.com/public/v1/auth' \
  -H "Authorization: Bearer $IMMOTEUR_TOKEN"
```

For token and data-access setup, see [API tokens and data access](./configuration). For endpoint-specific errors, use the generated API reference.