> ## Documentation Index
> Fetch the complete documentation index at: https://docs.donate.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits

> Understand how rate limiting works across the Developer API

The Developer API enforces rate limits on a **per-project** basis using a sliding window algorithm. All API keys under the same project share a single rate limit bucket. Limits are not per-key or per-endpoint.

## Limits by tier

| Tier           | Requests per minute |
| -------------- | ------------------- |
| **Free**       | 50                  |
| **Pro**        | 200                 |
| **Enterprise** | 1,000               |

All endpoints under the Developer API share the same counter. A `GET /charities` call and a `POST /configs` call both count toward the same per-minute limit for your project.

## Response headers

Every successful response from a rate-limited tier includes headers describing your current usage:

| Header                  | Description                                       |
| ----------------------- | ------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window    |
| `X-RateLimit-Remaining` | Requests remaining in the current window          |
| `X-RateLimit-Reset`     | Unix epoch seconds when the current window resets |

These headers are included on both successful responses and `429` responses.

## When you're rate limited

If you exceed your tier's limit, the API returns a `429` status with an additional `Retry-After` header:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

| Header        | Description                             |
| ------------- | --------------------------------------- |
| `Retry-After` | Seconds until you can retry the request |

The request handler is **not invoked** when it is rate limited. No side effects occur and no data is modified.

## 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 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.

## Upgrading your limit

If you're hitting rate limits regularly, you may be eligible for a higher tier. Contact us at [support@donate.gg](mailto:support@donate.gg) to discuss upgrading your project's tier.