# Rate limits

> How the /v1 server API signals rate limiting — 429 with Retry-After — the published webhook limits, and how to back off.

Source: https://docs.getbeekon.com/api/rate-limits/

This page lists the published limits and how to back off. When a request is rate limited, the API answers:

```plaintext
HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json


{"error":"rate limited"}
```

* `Retry-After` is an integer number of seconds, from 1 to 3600. Wait at least that long before retrying.
* A `429` never changes what your request meant: retry the same request, with the same cursor. A rate-limited request did nothing.
* Branch on the status code, not on the `error` text.

## Published limits

| What                                                       | Limit                                                                                  | Counted per      |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------------- |
| Webhook writes: create, `PATCH`, `DELETE`, `rotate-secret` | 1 per second, bursts of up to 20                                                       | project          |
| Webhook pings                                              | 1 per minute, bursts of up to 3                                                        | webhook endpoint |
| Webhook pings                                              | 20 per hour, bursts of up to 20                                                        | project          |
| Webhook endpoints                                          | at most 10 per project (a quota: `409 webhook_limit_reached`, not a `429`)             | project          |
| Active device commands                                     | at most 20 unexpired, unfulfilled commands per device (`409 too_many_active_commands`) | device           |
| User erasure: `DELETE /v1/users/{user_id}`                 | 30 calls a minute, bursts of up to 30 (`429 rate limited`)                             | key              |

Webhook limits count per project, not per key: issuing more keys does not raise them. They are enforced per API server, so under load you may occasionally get slightly more than the limit, never less.

## Other limits

* **Uploads** (`POST /v1/ingest`) are limited **per key**: each credential has its own budget, so one busy key does not slow another. The budget is set per deployment and is not published. Over it, ingest answers `429` with its own body, `{"error":"rate limit exceeded for this credential, retry"}`, and a `Retry-After`.
* **Reads** (`GET` on project, devices, users, locations, trips, geofences, config document, events and webhooks) have no published per-key limit today.
* Any endpoint may answer `429` or `503` while the platform protects itself. Both always carry `Retry-After`. Handle both on every call.

Note

Write your client to honour `Retry-After` rather than to a fixed request rate. New limits are announced in the [changelog](https://docs.getbeekon.com/api/changelog/).

## Backing off

* On `429` or `503`: sleep for `Retry-After` seconds (add a little jitter), then retry. Two ingest `503`s are the exception: a retry does not fix `unsupported schema_version` or `project suspended`. See [Ingest](https://docs.getbeekon.com/api/ingest/#errors).
* On a `5xx` without `Retry-After`: retry with exponential backoff and jitter, for example 1 s, 2 s, 4 s … capped at a minute.
* Run walks sequentially per key rather than fanning out many parallel walks; a larger `limit` (up to 500) is cheaper than more concurrent requests.
