Skip to main content

Rate Limiting

How the ZENTRA Cloud v5 API rate limits requests per user with the GCRA algorithm — burst and steady-state limits, reset behavior, and handling 429 responses.

Rate Limiting

The v5 API is rate limited per user — based on the user resolved from your API key, independent of any device. Requests beyond your limit return 429 Too Many Requests.

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 client 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.

v5 has a burst limit of 5 and a steady-state rate of 1 request per minute.

How GCRA works in v5

  • Initial burst allowance. After being idle, a client can make up to 5 immediate requests with no delay. This is the allowed burst capacity.
  • Steady-state rate. Once the burst capacity is consumed, further requests are limited to the steady rate of 1 request per minute.
  • Burst reset behavior. The burst allowance fully resets after an idle period equal to burst_limit × 60 seconds (for 5 bursts, that's 300 seconds). After this idle period, the client regains the full burst allowance.
  • Handling early requests. If a request arrives sooner than GCRA allows, the algorithm calculates a next time to call timestamp. The client must wait until then before its next request will be accepted.

Handling 429 responses

When you receive 429 Too Many Requests, back off before retrying rather than immediately retrying in a loop. Where the response provides a next time to call value, wait until that time. A simple approach is to pace sustained traffic to the steady-state rate and reserve the burst allowance for interactive or one-off calls.

See Errors for the full status-code reference.

How did we do?

API Token

Errors

Contact