# Rate limits

> The API allows **100 requests per second per IP address**. The limit is counted on each
> API instance separately, so treat 100/s as the most you can rely on, not a guarantee.

Every response carries three headers describing your current window:

```text title="Rate-limit headers"
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1
```

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | Maximum requests allowed in the current window. |
| `X-RateLimit-Remaining` | Requests left before you're throttled with a `429`. |
| `X-RateLimit-Reset` | Seconds until the window resets and `Remaining` refills. |

When you go over the limit, the API returns **429** with error code `5` and a
`Retry-After` header: the number of seconds to wait.

:::note Browsers can't read these headers
The API doesn't expose the rate-limit headers through CORS, so code running in a browser
can't see them. API tokens belong on your server anyway; call the API from there.
:::

## Handling `429`s

- Check `X-RateLimit-Remaining` before firing a burst of requests, not just
  after you've already been throttled.
- On a `429`, wait at least `Retry-After` seconds, with jitter, before retrying. Don't
  retry immediately in a loop.
- Prefer subscribing over [WebSockets](/realtime/connecting) to anything
  that changes in realtime (occupancy, gateway state) instead of polling the
  REST API for it.

## Next step

See [Errors](/api/errors) for how failed requests, including a `429`, are
shaped, or the [API Reference](/api) for individual endpoints.