# Rate limits

> BloomText API rate limits, rate limit headers, and how to stay under them.

Source: https://www.bloomtext.com/developers/api/rate-limits/

API key limits apply to each organization. All of an organization's API keys share them, so a second key doesn't add to them. A key that reaches several organizations counts each call against the organization it names with `org_id`; a call that names none, like [`GET /orgs`](https://www.bloomtext.com/developers/api/reference/list-orgs/), counts against the key itself.

- **Requests from an organization's API keys:** 300 per minute, with bursts of up to 10 requests per second. [Imports](https://www.bloomtext.com/developers/api/patients/#import-patients) and [campaigns](https://www.bloomtext.com/developers/api/campaigns/) count as one request each, however many patients they cover.
- **Messages from an organization's API keys:** 60 per minute. Every message you send counts, one by one or in a [batch](https://www.bloomtext.com/developers/api/send-messages/#sending-to-many-patients). A batch of up to 60 messages counts as one request. A request whose messages don't fit in what's left of the minute is refused whole with `429`, and none of its messages are sent.
- **Each [OAuth](https://www.bloomtext.com/developers/api/oauth/) connection** (one admin connected to one app): 60 requests per minute, with bursts of up to 10 requests per second. Your app also has an overall limit, set when we register it.

## Rate limit headers

Every response to a valid API key includes these headers, errors included. A request with a missing or invalid key gets `401` without them.

| Header | Meaning |
| --- | --- |
| `RateLimit-Limit` | Requests allowed per minute. On a `429`, the limit that was hit: requests per minute, requests per second, or messages per minute. |
| `RateLimit-Remaining` | What's left in that window. |
| `RateLimit-Reset` | Seconds until that window resets. |
| `Retry-After` | On `429` responses only: whole seconds to wait before retrying. |

```http filename="Response · 429 Too Many Requests"
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 12
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 12
```

## Handle a 429

1. Wait the number of seconds in `Retry-After`.
2. Send the same request again **with the same `Idempotency-Key`**. A request refused with `429` was never run, so retrying it can't send anything twice. A new key would be a new request; see [Idempotency](https://www.bloomtext.com/developers/api/idempotency/#retry-safely).
3. If you get `429` again, keep waiting `Retry-After`, and back off further each time.

## Stay under the limit

- **Read only what's new.** Request messages with `after` set to the newest one you've seen instead of re-reading a whole range. Polling every 1 to 5 minutes is enough. See [Read messages](https://www.bloomtext.com/developers/api/read-messages/#keep-up-with-new-messages).
- **Read across conversations at once.** One [List messages](https://www.bloomtext.com/developers/api/read-messages/) request with a time range replaces a request per conversation.
- **Page with `page[limit]=100`.** Larger pages mean fewer requests. See [Pagination](https://www.bloomtext.com/developers/api/pagination/).
- **Back off exponentially** after a `429` or `503`, starting from `Retry-After` when it's present.
- **Spread out batch jobs.** Digests for 300 clinicians that all run at 7:00 sharp hit your app's overall limit. Stagger them over the hour before the clinic opens.

> **Note:** Need higher limits? BloomText can raise them for your organization on request. Mention it when you [request API access](https://calendly.com/tyler-bloom/bloomtext-homepage-demo-request?utm_campaign=api-access), or ask your BloomText contact.
