Errores y diagnóstico
Separá los errores del request de los fallos de entrega al canal. Guardá método, ruta, código HTTP y una respuesta sin datos sensibles para poder investigar.
Qué significa cada código
| Código | Qué revisar | ¿Reintentar? |
|---|---|---|
400 |
Formato o acción no admitida. | Corregí el request primero. |
401 |
Token ausente/inválido o permisos insuficientes. El CRM también usa este código para rechazos de autorización. | No, hasta corregir acceso o token. |
403 |
Acceso prohibido por un control de la instalación. | No automáticamente. |
404 |
Cuenta/recurso inexistente, cuenta incorrecta o ID que no corresponde. | Verificá los IDs. |
422 |
Validación: parámetros, datos del contacto, formato del mensaje o capacidades del canal. | Corregí el dato indicado. |
429 |
Límite de solicitudes alcanzado. | Esperá y reducí el ritmo. |
500, 502, 503, 504 |
Fallo del servidor o intermediario. | En lecturas, con espera y un máximo de intentos. En escrituras, verificá antes si se aplicaron. |
Los errores no tienen un único esquema. El detalle puede estar en error o message, y una validación puede incluir attributes. Un proxy puede devolver texto o HTML; no asumas que todo error es JSON.
El token funciona en una ruta pero no en otra
- Verificá que el
account_idsea el de la cuenta a la que pertenece ese usuario. - Confirmá que el usuario tenga acceso a la bandeja de esa conversación.
- Revisá si la operación requiere administrador (por ejemplo, administrar webhooks).
- Revisá roles personalizados y restricciones de asignación.
Si el cuerpo dice You are not authorized to do this action, puede ser un problema de permisos aunque el código sea 401.
La conversación existe, pero recibo 404
Usá el id público que devuelve la API y que aparece en /app/accounts/{account_id}/conversations/{id}. Los IDs de conversaciones son relativos a la cuenta. No uses un ID interno de una base de datos ni el contact_id.
El request de envío fue exitoso, pero el mensaje no llegó
Buscá el mensaje por su ID en el historial. Revisá status, content_attributes.external_error, la conexión de la bandeja, el destinatario y el permiso del canal para enviar en ese momento.
Un 200 de creación no es un acuse de entrega. Seguí mensajes y adjuntos para interpretar sent, delivered, read y failed.
Reintentos de lectura
Para consultas GET, usá un timeout, espera exponencial con variación aleatoria y un máximo de intentos. En un 429, respetá Retry-After si algún intermediario lo agrega; el limitador de esta aplicación no lo incluye por defecto. No ocupes todo el cupo de la cuenta: lo compartís con los agentes.
El script de exportación incluye una política acotada de reintentos. Agotar los intentos debe producir un error visible, no un archivo que parezca completo.
Un timeout de escritura es un resultado incierto
Si un POST se corta, el servidor puede haber aplicado el cambio antes de perderse la respuesta. No reenvíes mensajes, creaciones o cambios de estado a ciegas. Consultá el estado actual, revisá tus registros y decidí si hace falta una nueva operación.
Los webhooks tampoco garantizan una única entrega. Deduplicar solo por id + event puede descartar cambios legítimos; seguí las recomendaciones de webhooks.
Qué incluir al pedir ayuda
- Fecha y hora con zona horaria.
account_id,inbox_idy el ID público de la conversación o mensaje afectado.- Método y ruta del request, código HTTP y respuesta relevante.
- Qué esperabas y qué ocurrió; si falla siempre o de forma intermitente.
- Un ejemplo mínimo que permita reproducirlo, reemplazando el token y los datos privados.
No compartas api_access_token, secretos de webhooks, archivos de clientes ni una exportación completa para reportar un error puntual.