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.