Rate Limiting

The v5 API rate limits each endpoint independently, and the two endpoints count requests against different things: List Devices is limited per user, Get Device Readings is limited per device. Requests beyond a limit return 429 Too Many Requests.

Limits by endpoint

Each row is a separate budget. Consuming your List Devices burst has no effect on your Get Device Readings allowance, and vice versa.

Because readings are counted per device, a client reading from 10 devices holds 10 independent readings budgets — 50 burst requests and 10 requests per minute in aggregate — alongside its single List Devices budget.

The readings budget belongs to the device, not to the caller. Every client with access to a device draws from that device's single budget, so multiple people or integrations polling the same device share one allowance and can throttle one another. A 429 from this endpoint does not identify which caller consumed the budget. For devices read by more than one client, coordinate a single polling schedule rather than sizing each client's loop independently.

The algorithm: GCRA

The API uses the Generic Cell Rate Algorithm (GCRA), a precise, burstable rate-limiting algorithm. GCRA tracks a Theoretical Arrival Time (TAT) for each budget and allows a request as long as it does not arrive "too early" according to the configured rate. It's widely used in telecommunications, API gateways, and distributed systems where fairness and precise burst control matter.

How GCRA works in v5

The behavior below applies to every budget in the table above, using that row's burst limit and steady-state rate.

• Emission interval. The steady-state rate expressed as a spacing between requests: 60 ÷ requests per minute. At the current rate of 1 request per minute, the emission interval is 60 seconds.
• Initial burst allowance. From a fully idle state, a client can make up to burst_limit immediate requests with no delay. This is the allowed burst capacity.
• Steady-state rate. Once the burst capacity is consumed, further requests are accepted at the steady rate — one per emission interval.
• Capacity recovery. Capacity returns gradually rather than all at once: each emission interval of idle time restores one request. Full burst capacity is available after burst_limit × emission_interval of idle time — 300 seconds at the current settings.
• Handling early requests. If a request arrives sooner than GCRA allows, the algorithm calculates a next time to call. The client must wait until then before its next request will be accepted.

Handling 429 responses

A 429 Too Many Requests response tells you how long to wait in three places:

• Retry-After header — the number of whole seconds to wait before retrying. A request sent after that many seconds will not be rejected as too early. Most standard HTTP retry libraries read this header automatically.
• retry_after_seconds in the response body — the same number as the Retry-After header.
• detail in the response body — a message that includes the earliest time the next request will be accepted, as an absolute Unix timestamp in epoch seconds. It is kept for existing integrations; new integrations should use Retry-After.

{
  "detail": "Too many requests, please try again at or after this time 1787180708.",
  "retry_after_seconds": 43
}

Wait the Retry-After interval rather than retrying in a loop. Pace sustained traffic to the steady-state rate and save the burst allowance for interactive or one-off calls. A 429 from Get Device Readings can be caused by another client reading the same device, so slowing your own loop does not always clear it.

See HTTP Status Codes for the full status-code reference.