# rate_limit_exceeded

Source: https://capacms.com/docs/errors/rate_limit_exceeded

429 rate_limited. Capa refused the request to protect the service, for one of two reasons the message names: too many reads running at once (the API's read gate, per client, per key or per project), or too many uncached requests from this key in a minute (the CDN's limit).

| HTTP status | `type`         | Surfaces      |
| ----------- | -------------- | ------------- |
| 429         | `rate_limited` | REST, GraphQL |

## What it means

Capa refused the request to protect the service, for one of two reasons the message names: too many reads running at once (the API's read gate, per client, per key or per project), or too many uncached requests from this key in a minute (the CDN's limit).

| When                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | What the `hint` tells you |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| one client with 3 reads running with a key and 64 more waiting, the client with the most reads waiting when a key has 4 running and 256 waiting across its clients (a client with fewer waiting takes that client's newest place), a project whose keys together have 4 reads running (`This project has too many reads running at once across its keys.`), or a read that waited out the database budget behind one of those shares. GraphQL documents count toward the same shares, and another client of the key is still served. A client is its address, or its /64 for IPv6 | retry after `Retry-After` |

## What to do

Send fewer reads at once and retry after the Retry-After seconds; if the message counts requests in a minute, also cache GET responses, since cached reads are not counted.

## The response

HTTP 429:

```json
{
  "error": {
    "type": "rate_limited",
    "code": "rate_limit_exceeded",
    "message": "This client has too many reads running at once with this key.",
    "docs": "https://docs.capacms.com/errors/rate_limit_exceeded"
  },
  "meta": {
    "version": "2026-10-01",
    "contract": 1,
    "requestId": "req_0f3c…"
  }
}
```

## On GraphQL

`/api/graphql` answers the same `code` inside `errors[].extensions`. The status depends on the `Accept` header you send ([status codes](https://capacms.com/docs/api/graphql#status-codes)):

| `application/json` | `graphql-response+json` | When                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 429                | 429                     | your client already has 3 reads running with the key and 64 waiting (`This client has too many reads running at once with this key.`), your client is the one with the most reads waiting when the key has 4 running and 256 waiting across its clients (a client with fewer waiting takes the place of that client's newest read), your project's keys together have 4 reads running (`This project has too many reads running at once across its keys.`), your project has had 10 introspection answers computed and asks for another within the second (`This project has had too many different introspection answers computed in a short time.`), or a document waited longer than the database budget for a slot while one of those shares was full. GraphQL documents and `/api/entries` reads share them. Another client of the same key is still served. A client is its address, or its /64 for IPv6. `Retry-After` says when to try again |

## See also

* [Limits](https://capacms.com/docs/api/limits)
* [Caching](https://capacms.com/docs/api/entries#caching)