Saltar al contenido principal
Cada API key tiene dos buckets independientes de 60 requests por minuto, contra una ventana deslizante:
  • General — lecturas, tags, mailbox, notes, files.
  • Mensajes — envíos bajo conversation.messages.* (text, quick-reply, template).
Saturar uno no afecta al otro: puedes agotar el bucket de mensajes y seguir leyendo conversaciones (y al revés).

Cuando se excede

Al pasar el límite la API responde 429 con código RATE_LIMIT_EXCEEDED:

Headers de la respuesta

Todo 429 trae Retry-After. Los X-RateLimit-* solo acompañan al 429 de rate limit (code: RATE_LIMIT_EXCEEDED); otros 429 como TOO_MANY_PENDING_UPLOADS traen únicamente Retry-After:
integer
Segundos a esperar antes de reintentar.
integer
El límite del bucket que aplicó al request (60 en cualquiera de los dos).
integer
Requests disponibles en la ventana actual del bucket que aplicó.
integer
Momento en que la ventana se reinicia.

Cómo manejar un 429

1

Detecta el status

Casi todo 429 es rate limit. Respeta siempre el header Retry-After; si necesitas la causa exacta, distíngela por el campo code del body (RATE_LIMIT_EXCEEDED frente a otros como TOO_MANY_PENDING_UPLOADS).
2

Lee el Retry-After

Espera la cantidad de segundos que indica el header Retry-After.
3

Reintenta con backoff

Reenvía el request. Para cargas grandes (campañas), espacia los requests en vez de mandarlos en ráfaga.