Skip to main content
Each API key has two independent buckets of 60 requests per minute, against a sliding window:
  • General — reads, tags, mailbox, notes, files.
  • Messages — sends under conversation.messages.* (text, quick-reply, template).
Saturating one doesn’t affect the other: you can exhaust the messages bucket and keep reading conversations (and vice versa).

​
When exceeded

Past the limit the API responds 429 with code RATE_LIMIT_EXCEEDED:

​
Response headers

Every 429 carries Retry-After. The X-RateLimit-* headers accompany only the rate-limit 429 (code: RATE_LIMIT_EXCEEDED); other 429s such as TOO_MANY_PENDING_UPLOADS carry Retry-After alone:
​
integer
Seconds to wait before retrying.
​
integer
The limit of the bucket that applied to the request (60 in either one).
​
integer
Requests available in the current window of the bucket that applied.
​
integer
The moment the window resets.

​
How to handle a 429

1

Detect the status

Almost every 429 is a rate limit. Always honor the Retry-After header; if you need the exact cause, tell it apart by the body’s code field (RATE_LIMIT_EXCEEDED vs others such as TOO_MANY_PENDING_UPLOADS).
2

Read the Retry-After

Wait the number of seconds indicated by the Retry-After header.
3

Retry with backoff

Resend the request. For large workloads (campaigns), space out the requests instead of sending them in a burst.