Skip to content

Rate limits

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 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.
WhatLimitCounted per
Webhook writes: create, PATCH, DELETE, rotate-secret1 per second, bursts of up to 20project
Webhook pings1 per minute, bursts of up to 3webhook endpoint
Webhook pings20 per hour, bursts of up to 20project
Webhook endpointsat most 10 per project (a quota: 409 webhook_limit_reached, not a 429)project
Active device commandsat 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.

  • 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.
  • On 429 or 503: sleep for Retry-After seconds (add a little jitter), then retry. Two ingest 503s are the exception: a retry does not fix unsupported schema_version or project suspended. See Ingest.
  • 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.