Skip to Content
API access is available to organizations with a signed BAA. Request API access →
Rate limits

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, 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 and 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. 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 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.

HeaderMeaning
RateLimit-LimitRequests allowed per minute. On a 429, the limit that was hit: requests per minute, requests per second, or messages per minute.
RateLimit-RemainingWhat’s left in that window.
RateLimit-ResetSeconds until that window resets.
Retry-AfterOn 429 responses only: whole seconds to wait before retrying.
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.
  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.
  • Read across conversations at once. One List messages request with a time range replaces a request per conversation.
  • Page with page[limit]=100. Larger pages mean fewer requests. See 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.

Need higher limits? BloomText can raise them for your organization on request. Mention it when you request API access, or ask your BloomText contact.

Last updated on
ErrorsChangelog