Saltar al contenido

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.

Revisado el API 1.158.0 4 min de lectura

  • 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-Limit y X-RateLimit-Remaining. Respeta Retry-After; reintentar antes solo alarga el castigo.

Los errores vienen siempre con la misma forma:

JSON
{"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/permissions 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/{id}/quality 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)
Escríbenos por WhatsApp Te contesta nuestro agente de IA al momento