This page lists the published limits and how to back off. When a request is rate limited, the API answers:
HTTP/1.1 429 Too Many RequestsRetry-After: 2Content-Type: application/json
{"error":"rate limited"}Retry-Afteris an integer number of seconds, from 1 to 3600. Wait at least that long before retrying.- A
429never 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
errortext.
Published limits
Section titled “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
Section titled “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 answers429with its own body,{"error":"rate limit exceeded for this credential, retry"}, and aRetry-After. - Reads (
GETon project, devices, users, locations, trips, geofences, config document, events and webhooks) have no published per-key limit today. - Any endpoint may answer
429or503while the platform protects itself. Both always carryRetry-After. Handle both on every call.
Backing off
Section titled “Backing off”- On
429or503: sleep forRetry-Afterseconds (add a little jitter), then retry. Two ingest503s are the exception: a retry does not fixunsupported schema_versionorproject suspended. See Ingest. - On a
5xxwithoutRetry-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.