Skip to main content

Rate limits

The REST API accepts up to 5 requests per second per API key. This page explains how the limit works and how to build your integration so it stays under it.

How the limit works​

  • 5 requests per second per API key. The limit counts per client_id. Every access token requested with that client_id shares the same 5 requests per second, so requesting extra tokens does not add capacity.
  • One budget for everything that uses the same credentials. Every server, worker and scheduled job that authenticates with the same client_id draws from the same 5 requests per second.

Rate limit headers​

Every REST response includes three headers that show where you are within the limit:

HeaderMeaning
X-RateLimit-LimitRequests allowed per second (5)
X-RateLimit-RemainingRequests left in the current second
X-RateLimit-ResetSeconds until the counter resets

When a request goes over the limit​

A request over the limit is refused with 429 Too Many Requests:

curl -i https://api.helice.cloud/v2/products/sku/QSFP-40G-SR4 \
  -H "Authorization: Bearer ACCESS_TOKEN"
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1

{"error_msg":"Too many requests"}

The response has no Retry-After header. Use X-RateLimit-Reset to decide how long to wait.

A refused request has not been processed. Propeller rejects it before doing anything with it, so it is safe to send the same request again, including POST, PUT and DELETE requests.

Stay under the limit​

  1. Pace your requests on your side. Send at most 5 requests per second per client_id, for example with a queue or a token bucket. Limiting how many requests run at the same time is not enough: 5 parallel requests that each take 100 ms add up to 50 requests per second.
  2. Share the budget between processes. If several servers or jobs use the same client_id, send their calls through one queue, or give each a fixed share of the 5 requests per second.
  3. Reuse your access token until it expires. The expires_in value in the token response tells you how long that is, currently 30 minutes. Don't request a new token for every call. See Authentication and Security.
  4. Do more per request. Use bulk endpoints instead of one call per record. Use search endpoints with larger page sizes. See Batch sizing and Pagination. Cache data that rarely changes, such as product and category data.
  5. Spread scheduled work. Imports and synchronizations that start at the same moment share the same 5 requests per second.

Retry after a 429​

  • Wait at least X-RateLimit-Reset seconds, or 1 second if the header is 0 or missing. Then send the same request again.
  • If it is refused again, wait longer each time: 1 second, 2 seconds, 4 seconds and so on, with a small random delay added. Stop after a few attempts.
  • Log every 429. Regular 429 responses mean your integration sends requests faster than 5 per second.

See also​