Skip to main content

Plan your request budget

Reads and writes share the budget. Each HTTP request counts once, including a bulk request. Browser sessions are outside this API-client limiter. Coordinate concurrent workers that share a budget. Use employee pagination to reduce requests, and spread work across the minute instead of sending a burst. For example, a single worker sending five requests per second leaves room in a 500/minute budget, provided other workers don’t consume the remaining capacity.

Read response headers

The API-client limiter uses these headers. Header names are case-insensitive; these values are illustrative:
  • limit is the request budget for the window.
  • remaining is the number of requests left in that budget.
  • reset is the number of seconds until the window resets, not a Unix timestamp.
  • w=60 is the policy window in seconds.
Read these values dynamically. On a limited request, remaining is 0 and the server adds Retry-After, a delay in seconds:
The response uses the standard API v2 error envelope with error.code: "RATE_LIMITED".

Handle a 429

Wait at least Retry-After seconds before retrying. This Python example uses the standard library to make an employee search and retries a 429 up to three times:
Use the environment variables from Making requests. After a retry succeeds, pace subsequent requests and coordinate other workers; immediately sending another burst can exhaust the next window. Retry decisions for writes also need the write-safety checks.