Rate limits

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:

{ "code": "RATE_LIMIT_EXCEEDED", "message": "..." }

Toda resposta 429 inclui estes headers:

Retry-After

integer

Segundos a esperar antes de repetir.

X-RateLimit-Limit

integer

O limite do bucket que aplicou ao request (60 em qualquer um dos dois).

X-RateLimit-Remaining

integer

Requisições disponíveis na janela atual do bucket que aplicou.

X-RateLimit-Reset

integer

Momento em que a janela é reiniciada.

Detecte o status

Trate qualquer resposta 429 como rate limit, sem parsear o body.

Leia o Retry-After

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

Repita com backoff

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