Skip to main content
Rate limits are enforced on Donate /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. New organizations start on Free. Owners and admins can switch to Pro or Enterprise under Billing in the developer portal. Unlimited is a sales grant.

​
Anonymous public GET (no API key)

Catalog GET/HEAD routes may omit donate-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 a 429 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.
  • Watch new charities on GET /charities/feed (or GET /charities/feed.atom). That response stays cached until a charity write revalidates it. Search is a typeahead, not a change feed.
  • Respect Retry-After. When you receive a 429, wait at least the number of seconds indicated before retrying.
  • Monitor your headers. Use X-RateLimit-Remaining to 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.

​
Upgrading your limit

Upgrade to Pro or Enterprise from Billing in the developer portal (owners and admins). If you need Unlimited, email support@donate.gg.