/api/v1 before the route handler runs. A 429 means the handler was not invoked.
API keys (per organization)
Authenticated calls share one sliding-window bucket per developer organization. All API keys across every project in that organization count together. Limits are not per-key, per-project, or per-endpoint.
Unlimited-tier organizations skip this meter.
Anonymous public GET (no API key)
Catalog GET/HEAD routes may omitdonate-api-key. Unauthenticated calls use a stricter IP-based budget intended for light public reads (about 20 requests per minute per client).
Do not rely on anonymous access for production integrations, scrapers, or bulk sync. Use an API key when you need a higher, billable organization limit or when the route requires a known caller.
The Donate website itself may receive a higher anonymous browse budget for first-party UI traffic. That allowance is not part of the public integrator contract and must not be treated as a documented client API.
Response headers
Every successful response from a rate-limited bucket includes headers describing current usage:
These headers are included on both successful responses and
429 responses.
When you’re rate limited
If you exceed the active budget, the API returns a429 status with an additional Retry-After header:
Best practices
- Cache responses when possible to reduce unnecessary calls, especially for data that changes infrequently like the charity list or chain list.
- Respect
Retry-After. When you receive a429, wait at least the number of seconds indicated before retrying. - Monitor your headers. Use
X-RateLimit-Remainingto slow down before you hit the limit. - Spread requests over time rather than sending them in bursts at the start of each window.
- Prefer a key for server integrations. The anonymous budget is for light public reads, not bulk sync.