Rate limits
The API is rate-limited per organisation. Read the headers and retries become boring.
The limit
- 100 requests per second per organisation, with a burst of 100. Token-bucket policy.
- The limit is shared by every API key in the organisation. If you need more, talk to us before sharding keys.
- Sandbox and live each get their own budget. A tight retry loop in sandbox cannot exhaust your live quota.
Headers on every response
We emit both the IETF draft-10 RateLimit-* family and the older X-RateLimit-* family. Use whichever your tooling understands.
| Header | Meaning |
|---|---|
| RateLimit-Limit | Requests allowed in the window. |
| RateLimit-Remaining | Requests remaining in the current window. |
| RateLimit-Reset | Seconds until the window resets (relative). |
| RateLimit-Policy | 100;w=1;policy="token bucket". |
| X-RateLimit-Limit | Same as RateLimit-Limit. |
| X-RateLimit-Remaining | Same as RateLimit-Remaining. |
| X-RateLimit-Reset | Unix epoch (seconds) when the window resets (absolute). |
When you are throttled
Exceeding the limit returns 429 rate_limited with a Retry-After header (seconds):
HTTP/1.1 429 Too Many Requests
Retry-After: 1
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1
{
"error": {
"type": "https://alltogether.giving/developer/api/errors/rate_limited",
"code": "rate_limited",
"message": "Too many requests. Slow down and retry after the window resets.",
"request_id": "req_..."
}
}- Sleep for
Retry-Afterseconds, then retry. - Pair the retry with an Idempotency-Key so the eventual successful call cannot double-write.
- If you're consistently hitting the ceiling, add backpressure on the client side. A bounded queue and a worker pool with concurrency below 100 is usually enough.
Staying under the ceiling
- Watch
RateLimit-Remainingon every response. Pause bulk jobs when it drops below a threshold you pick. - Filter server-side rather than fetching and filtering in the client. Every endpoint supports bracket filters and pagination.
- For large exports, walk pages in series. Parallel exports against the same organisation will just burn your burst.
Rate limits are per organisation, not per API key. Spinning up more keys for the same organisation does not raise the ceiling.
Related
- Error envelope and codes: the shape of
rate_limited. - Idempotency: safe retries after a 429.