Apartado 8 de 15 · Referencia
Límites y errores
600 peticiones y 60 envíos por minuto, y qué significa cada 401, 403, 404, 422 y 429 de la API de Chatendo, con lo que hay que hacer en cada caso.
- 600 peticiones por minuto por usuario del token.
- 60 envíos por minuto para los mensajes salientes.
- Al pasarse: 429 con
Retry-After,X-RateLimit-LimityX-RateLimit-Remaining. RespetaRetry-After; reintentar antes solo alarga el castigo.
Los errores vienen siempre con la misma forma:
{"message": "Insufficient token scope.", "code": "TOKEN_SCOPE_DENIED", "required": ["conversations:read"]}No te dejan pasar — es cosa del token o del id:
| Código | Qué pasó | Qué hacer |
|---|---|---|
401 UNAUTHENTICATED |
Falta el token, está mal escrito o fue revocado | Revisar la cabecera; si sigue, crear otro |
401 TOKEN_EXPIRED |
El token tenía fecha de caducidad y ya pasó | Crear otro en el panel y cambiarlo en la integración |
403 TOKEN_SCOPE_DENIED |
Al token le falta el permiso de esa ruta, o la ruta es solo del panel | Crear un token con el permiso que dice required; si required viene vacío, no tiene vuelta por API |
403 FORBIDDEN |
El rol de la persona que creó el token no deja hacer eso (un token nunca puede más que ella, §3) | GET /me dice qué le deja; o que le den ese permiso a su rol, o crear el token con otra persona |
403 REQUIRES_SESSION_AUTH |
Eso solo se hace desde el panel | No tiene vuelta por API |
403 APP_INACTIVE |
La ruta es de una app (Tareas, Embudo, Empresas, Campañas…) y está apagada en tu cuenta | Encenderla en Ajustes → Aplicaciones |
404 |
No existe o es de otro inquilino | Comprobar que el id es de tu cuenta |
404 CONTACT_NOT_FOUND |
El contact_id del cuerpo (al enlazar o descartar, §6.7) no existe, es de otra cuenta o queda fuera del alcance del token |
Comprobar el id con GET /contacts |
Te dejan pasar pero el dato o el momento no valen:
| Código | Qué pasó | Qué hacer |
|---|---|---|
422 VALIDATION_ERROR |
Falta un campo o está mal | El cuerpo trae errors campo por campo |
422 UNKNOWN_QUERY_PARAM · INVALID_QUERY_PARAM · UNKNOWN_BODY_FIELD |
Un parámetro de la consulta (o un campo del cuerpo) que esa ruta no admite, o una lista donde cabe un solo valor | allowed dice cuáles sí admite (§6.5) |
422 WINDOW_EXPIRED |
Texto libre fuera de las 24 h | Mandar plantilla aprobada |
422 PHONE_INVALID / PHONE_TAKEN |
Teléfono inválido, o ya existe | Buscar y enlazar, no crear |
422 SAME_CONTACT / PLATFORM_NOT_LINKABLE |
Al enlazar dos contactos como una persona (§6.7): son el mismo, o uno es de LinkedIn | Mandar otro contacto; LinkedIn no se enlaza |
422 SSRF_BLOCKED |
La URL del webhook no es pública | Usar una dirección accesible desde fuera |
422 QUALITY_PROTECTION_ACTIVE |
Una plantilla de marketing con el número en rojo, marcado o restringido por Meta y «Proteger mi número» encendido | No es un fallo tuyo: el freno se suelta solo cuando Meta sube la calidad. Mientras, salen las respuestas dentro de las 24 h y las plantillas de utilidad; GET /channels dice en qué estado está |
422 IDEMPOTENCY_KEY_REQUIRED |
Un envío de mensaje o de archivo sin la cabecera Idempotency-Key |
Ponerla (§6.2) |
422 IDEMPOTENCY_KEY_INVALID |
La clave no tiene entre 8 y 64 caracteres, o lleva otros que no son letras, números, _, -, : o . |
Usar una clave válida (§6.2) |
422 IDEMPOTENCY_KEY_REUSED · 409 IDEMPOTENCY_KEY_IN_FLIGHT |
La misma clave con otros datos; o la primera petición con esa clave aún se está procesando | Una clave nueva para una operación distinta; si es la misma, esperar unos segundos y repetirla con la misma clave |
422 CHANNEL_UNAVAILABLE |
POST /outbound-messages en una cuenta sin número de WhatsApp conectado |
Conectar el número desde el panel (§6.8) |
409 CONTACT_DELETED · CONTACT_OPTED_OUT · NUMBER_WITHOUT_WHATSAPP |
POST /outbound-messages a un teléfono que está en la papelera, de baja o sin WhatsApp |
No escribirle; no se ha creado nada (§6.8) |
422 SEND_AT_TOO_SOON · CANNOT_CANCEL_NON_PENDING · ATTACHMENT_ON_EDIT_UNSUPPORTED |
Mensaje programado: hora a menos de 60 s, cancelar uno que ya no está pendiente, o añadir un archivo al editar | Ver §6.8 |
422 SEARCH_QUERY_TOO_SHORT |
La búsqueda de conversaciones lleva menos de 2 caracteres | Escribir al menos 2 |
422 BULK_LIMIT_EXCEEDED |
Una acción en bloque de conversaciones con más de 100 | Partirla en tandas de 100 |
409 DELIVERY_NOT_RETRYABLE · ENDPOINT_INACTIVE · 422 INVALID_CURSOR |
Reenviar una entrega que no está fallida; reenviar en un endpoint apagado; usar un cursor con otros filtros (§5.4) | Mirar su estado, encenderlo, o empezar sin cursor |
422 EMAIL_CONNECTION_FAILED |
Al conectar un buzón, cambiar su conexión o enviar un correo, el servidor de correo lo rechazó. Trae reason, step y hint |
Leer hint; los motivos, en §15.3 |
422 EMAIL_TYPE_UNSUPPORTED |
Ese tipo de envío (plantilla, botones, reacción…) o ese archivo no sale por correo | Mandar text o un archivo permitido (§15.5) |
429 |
Te pasaste del límite | Esperar lo que diga Retry-After |
429 EMAIL_RATE_LIMIT · EMAIL_TEST_RATE_LIMIT |
El buzón llegó a su tope de correos por hora, o a las 12 pruebas de conexión por hora | Esperar retry_after segundos (§15) |