Rate limit policies
Every request counts against two policies at the same time. A request is rejected as soon as either of them is exhausted.
Windows are fixed and aligned to the clock: the
default window resets at the start of every minute, and the burst window every 2 seconds. In practice, sending 600 requests at once gets rejected by the burst policy even though your per-minute quota is not used up. Spread your requests evenly (for example, at most 10 requests per second) to stay within both.
Rejected requests count too: a request refused by one policy still consumes quota from the other. Retrying immediately after a 429 therefore eats into your per-minute quota, so always wait for the time given by Retry-After.
We reserve the right to change these limits at any time. You should always rely on the response headers below rather than hard-coding them.
Rate limit headers
Every API response includes headers describing each policy and your current usage.Standard headers
folk implements the IETF RateLimit header fields, which describe every policy in a single header:RateLimit-Policy: The policies applied to the request.qis the number of requests allowed per window, andwis the window length in seconds.RateLimit: Your current usage of each policy.ris the number of requests remaining, andtis the number of seconds until the window resets.
Legacy headers
The following headers are also returned, one set per policy:Exceeding a rate limit
If you exceed a rate limit, you will receive a429 HTTP status code response and a Rate limit error. The error’s details tell you which policy was exceeded and the status of every policy.A
Retry-After header is also included in the response, indicating the number of seconds you should wait before making another request. When several policies are exceeded, it reflects the one that resets last.
Handling limiting gracefully
A basic technique for integrations to gracefully handle limiting is to watch for 429 status codes and build a retry mechanism using theRetry-After response header or the details.retryAfter property in the error response body.
A rate-limited request is rejected before it runs, so it never has side effects and is always safe to retry. To also retry safely after a timeout or a network error, send an Idempotency-Key.
The retry mechanism should follow an exponential backoff schedule to reduce request volume when necessary. We’d also recommend building some randomness into the backoff schedule to avoid a thundering herd effect.
To avoid hitting the limits in the first place, throttle your client using the RateLimit header: when r reaches 0 for a policy, wait t seconds before sending the next request.