Límites de uso
Los límites protegen la plataforma y, sobre todo, al panel de tus propios agentes: varios se cuentan por cuenta, así que una integración que consulta de más degrada la experiencia de tu equipo.
Tabla de límites
| Qué | Límite | Ventana | Se cuenta por |
|---|---|---|---|
| Cualquier request | 3.000 | 1 minuto | IP de origen |
GET .../conversations (listado) |
60 | 1 minuto | Cuenta (compartido con el panel) |
GET .../contacts/search |
300 | 1 minuto | Cuenta |
POST .../conversations/{id}/transcript |
30 | 1 hora | Cuenta |
POST .../upload (subir adjuntos) |
60 | 1 hora | Cuenta |
Inicio de sesión (/auth/sign_in) |
5 por IP, 10 por email | 5 y 15 minutos | IP / email |
El resto de los endpoints (POST .../conversations/filter, mensajes, detalle de conversación, contactos, etiquetas, webhooks, reportes) solo tienen el límite global por IP. Aun así, tratá el filtro de conversaciones con el mismo cuidado que el listado: pega en la misma base de datos que usa el panel.
Los valores de la tabla son los predeterminados; cada instalación puede ajustarlos. Si tu integración ve un 429 antes de lo esperado, revisá otros consumidores y la configuración de la instalación.
Qué pasa al superarlo
La respuesta es 429 Too Many Requests sin cuerpo útil y sin headers Retry-After ni X-RateLimit-*. Los contadores se reinician al terminar la ventana.
Recomendaciones:
- Ante un
429, esperá con backoff exponencial (1 s, 2 s, 4 s…) y reintentá. - Reservá margen para el panel: 1 request por segundo ya consume las 60 llamadas del minuto. Usá un ritmo menor y reducilo si aparecen errores o lentitud.
- No hagas polling para detectar novedades: usá webhooks y dejá la API para consultar detalle.
- Si exportás historial, seguí el ritmo sugerido en exportar historial.
Otros límites a tener en cuenta
| Aspecto | Valor |
|---|---|
| Tamaño de página de listados | 25 conversaciones o 15 contactos por página. |
| Mensajes por request | 20 por defecto; hasta 100 con history_scan=true y cursor before. |
| Timeout de webhooks | 5 segundos para responder 2xx. |
| Ventana de 24 h de WhatsApp | Fuera de ella, los mensajes salientes solo pueden ser templates aprobados. |
| Adjuntos | Según el canal; verificá formato y tamaño admitidos por la conexión antes de subir archivos; no existe un máximo único para todos los canales. |