<!-- Carebit docs: Rate limits -->

# Rate limits

The Developer Platform enforces rate limits at the Cloudflare edge, in
front of `api.carebit.co`. Every limit uses a rolling 60-second window.

| Limit                            | Value                     |
| -------------------------------- | ------------------------- |
| Per access token                 | 120 requests per minute   |
| Per developer project            | 240 requests per minute   |
| Per Organization                 | 300 requests per minute   |
| Writes per access token          | 30 requests per minute    |
| Writes per developer project     | 60 requests per minute    |
| Writes per Organization          | 90 requests per minute    |
| Patient creates per access token | 10 requests per minute    |
| `/oauth/token` per IP            | 10 requests per minute    |
| `/oauth/token` per `client_id`   | 10 requests per minute    |
| Unattributed requests per IP     | 120 requests per minute   |
| API backstop per IP              | 1,000 requests per minute |

**Per access token** is keyed on the SHA-256 hash of the raw bearer
token. The gateway never persists or logs the token itself.

**Write** limits apply to `POST`, `PUT`, `PATCH`, and `DELETE` requests
under `/v1`. They use separate counters and apply in addition to the
all-request limits above. Read requests do not consume write capacity.

**Patient create** limits apply to `POST /v1/patients` in addition to
the general write and all-request limits. This lower limit protects the
duplicate-review workflow from automated probing.

**Unattributed** requests are those the edge cannot map to a real project
or Organization yet: unauthenticated requests, fabricated tokens, and
real requests that arrive before Rails has cached the token's identity.

**API backstop** is a defense-in-depth per-IP limit applied to every
resource API request in addition to the tenant limits. It is higher than
the tenant limits because one integration IP typically serves several
Organizations.

## 429 response

When any limit is hit the API returns `429` with `Retry-After: 60`.

```
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{ "error": { "type": "rate_limit_error", "code": "too_many_requests",
  "message": "Too many requests. Please slow down." } }
```

Back off for at least the number of seconds in `Retry-After`, using the
same `Idempotency-Key` on any write retry so a duplicate write never
mutates state twice.

## Requesting a higher ceiling

Contact support with your project ID, an estimate of steady-state and
burst traffic, and the endpoint mix you are calling. Include the
`Carebit-Developer-Platform-API-Request-Id` header from a recent
`429` response so we can trace the throttle.
