Skip to main content
Cada API key tem dois buckets independentes de 60 requisições por minuto, contra uma janela deslizante:
  • Geral — leituras, tags, mailbox, notes, files.
  • Mensagens — envios sob conversation.messages.* (text, quick-reply, template).
Saturar um não afeta o outro: você pode esgotar o bucket de mensagens e continuar lendo conversas (e vice-versa).

​
Quando é excedido

Ao passar o limite a API responde 429 com código RATE_LIMIT_EXCEEDED:

​
Headers da resposta

Todo 429 traz Retry-After. Os X-RateLimit-* acompanham apenas o 429 de rate limit (code: RATE_LIMIT_EXCEEDED); outros 429 como TOO_MANY_PENDING_UPLOADS trazem somente Retry-After:
​
integer
Segundos a esperar antes de repetir.
​
integer
O limite do bucket que aplicou ao request (60 em qualquer um dos dois).
​
integer
Requisições disponíveis na janela atual do bucket que aplicou.
​
integer
Momento em que a janela é reiniciada.

​
Como tratar um 429

1

Detecte o status

Quase todo 429 é rate limit. Respeite sempre o header Retry-After; se precisar da causa exata, distinga-a pelo campo code do body (RATE_LIMIT_EXCEEDED frente a outros como TOO_MANY_PENDING_UPLOADS).
2

Leia o Retry-After

Espere a quantidade de segundos indicada pelo header Retry-After.
3

Repita com backoff

Reenvie a requisição. Para cargas grandes (campanhas), espace as requisições em vez de enviá-las em rajada.