Desarrolladores
Errores de la API
Cada error trae un code estable para tu código y un detail en español para las personas. Los códigos nuevos se añaden sin avisar: trata uno desconocido por su estado HTTP.
Códigos de error
| Código | HTTP | Qué pasa | ¿Reintentar? |
|---|---|---|---|
BAD_REQUEST | 400 | La petición está mal formada. JSON roto o cuerpo interrumpido. | No: corrige la petición. |
INVALID_CURSOR | 400 | El cursor no es válido. Manipulado, caducado, o de otra operación o de otros filtros. | No: empieza de nuevo sin cursor. |
API_KEY_EXPIRED | 401 | La clave caducó. Pasó su fecha de caducidad, también el fin de la gracia tras una rotación. | No: usa la clave nueva. |
API_KEY_INVALID | 401 | La clave no es válida. Otro esquema de autorización, formato o suma de control incorrectos, o una clave que no existe. | No. |
API_KEY_REVOKED | 401 | La clave está revocada. La clave se revocó, o el espacio se cerró. | No. |
API_KEY_SUSPENDED | 401 | La clave está suspendida. Quien la creó salió del espacio, bajó de rol, perdió números o tiene la cuenta desactivada. | No: rótala. |
UNAUTHENTICATED | 401 | Falta la clave. La petición no lleva la cabecera Authorization. | No. |
FEATURE_NOT_ENABLED | 403 | Esa función no está activa en este espacio. El espacio no incluye la API o, en /v1/webhook-endpoints, los webhooks y, al crear o borrar plantillas, las plantillas (required_capability). | No. |
FORBIDDEN | 403 | No se puede hacer. Borrar una plantilla que no se creó en el espacio, o un destino fuera de la lista permitida del entorno de pruebas. | No. |
INSUFFICIENT_SCOPE | 403 | La clave no tiene ese permiso. Falta el alcance que pide la operación (required_scopes). | No: crea o rota una clave con ese permiso. |
READ_ONLY | 403 | El espacio está en solo lectura. Una escritura con el espacio suspendido. | No. |
TEMPLATE_CATEGORY_NOT_ALLOWED | 403 | La clave no puede enviar esa categoría. La categoría de la plantilla no está entre las que permite la clave (reason). | No. |
WEBHOOK_CHANNELS_NOT_ALLOWED | 403 | Incluye números que la clave no alcanza. Números fuera de los de la clave, o «todos» con una clave limitada a algunos. | No. |
WEBHOOK_EVENTS_NOT_ALLOWED | 403 | La clave no puede recibir esos eventos. Eventos con datos de las conversaciones (message.* y call.ended) con una clave sin messages:read. | No: usa una clave con ese permiso. |
NOT_FOUND | 404 | No existe. Lo ajeno o inexistente (mensaje, archivo, número, plantilla) y cualquier ruta desconocida. | No. |
METHOD_NOT_ALLOWED | 405 | Método no admitido. La ruta existe, pero no con ese método (Allow dice cuáles). | No. |
CONFLICT | 409 | Conflicto. El archivo todavía se está guardando. | Sí, en unos segundos. |
IDEMPOTENCY_IN_PROGRESS | 409 | Esa petición se está procesando. Otra petición con la misma Idempotency-Key está en curso. | Sí, tras Retry-After. |
MEDIA_NOT_READY | 409 | El archivo todavía no está listo. El archivo de un mensaje recibido se está guardando: lo trae de WhatsApp el archivador. | Sí, tras Retry-After (30 s). |
UPLOAD_USED | 409 | El archivo ya se usó. Una subida sirve para un solo mensaje. | No: súbelo otra vez. |
WABA_IN_OTHER_WORKSPACE | 409 | La cuenta de WhatsApp Business está en otro espacio. Reservado: la v1 no conecta números. | No. |
WEBHOOK_LIMIT_REACHED | 409 | El espacio llegó a su máximo de endpoints. Ya tiene el máximo de endpoints de webhooks (10 por omisión), sin contar los eliminados. | No: elimina uno que no uses. |
WEBHOOK_STATE_CONFLICT | 409 | El endpoint no admite eso en su estado. Editar o probar un endpoint suspendido. | No: reactívalo en la consola. |
MEDIA_UNAVAILABLE | 410 | El archivo ya no está disponible. WhatsApp ya no lo tenía cuando se fue a buscar (lo guarda 7 días), o no se pudo descargar. | No. |
UPLOAD_EXPIRED | 410 | El archivo caducó. Pasaron más de 24 horas sin usarlo. | No: súbelo otra vez. |
LENGTH_REQUIRED | 411 | Falta el tamaño. Un multipart sin Content-Length. | No. |
PAYLOAD_TOO_LARGE | 413 | Demasiado grande. Un cuerpo JSON de más de 64 KB, o un archivo por encima de su límite. | No. |
UNSUPPORTED_MEDIA_TYPE | 415 | Tipo no admitido. El tipo de contenido de la petición, o el formato del archivo (reason). | No. |
RANGE_NOT_SATISFIABLE | 416 | El rango pedido no está en el archivo. Un Range que empieza después del final (Content-Range dice el tamaño). | No: pide un rango dentro del tamaño. |
IDEMPOTENCY_KEY_REUSED | 422 | Esa clave de idempotencia ya se usó con otra petición. La misma Idempotency-Key con otro contenido. | No: usa otra clave. |
MEDIA_REJECTED | 422 | WhatsApp no aceptó el archivo. Meta lo rechazó al subirlo. | No. |
MESSAGE_NOT_INBOUND | 422 | Ese mensaje no llegó de un contacto. Marcar como leído un mensaje enviado: solo se marcan los que llegan. | No. |
TEMPLATE_NOT_FOUND | 422 | La plantilla no existe. El nombre o el idioma no están en la cuenta del número. | No. |
TEMPLATE_NOT_SENDABLE | 422 | La plantilla no se puede enviar. reason: not_approved, authentication, location_header, media_header, unsupported o calling (lleva llamadas y el plan del espacio no las incluye o el número no las hace). | No. |
VALIDATION_FAILED | 422 | Los datos no son válidos. El esquema o las reglas del envío: errors[] trae la ruta y el código de cada problema. | No: corrígelos. |
WEBHOOK_EVENT_UNKNOWN | 422 | Ese evento no existe. Un tipo que no está en el catálogo de eventos. | No. |
WEBHOOK_URL_INVALID | 422 | La URL no sirve para un webhook. No es https:// con un dominio público y un puerto admitido, lleva usuario o contraseña, o es demasiado larga (reason). | No: corrígela. |
WEBHOOK_URL_NOT_ALLOWED | 422 | Esa dirección no está permitida. El dominio resuelve a una red privada o reservada, o a los servidores de StackNetic. | No: usa una URL pública de tu servidor. |
WEBHOOK_URL_UNRESOLVABLE | 422 | No encontramos ese dominio. El dominio de la URL no resuelve en el DNS. | Sí, cuando esté publicado. |
DAILY_LIMIT_REACHED | 429 | La clave llegó a su tope diario. Los envíos del día de la clave llegaron a su tope. | Sí, al día siguiente (Retry-After). |
QUEUE_FULL | 429 | Hay demasiados mensajes esperando. 5.000 mensajes pendientes en el espacio. | Sí, tras Retry-After. |
RATE_LIMITED | 429 | Demasiadas peticiones. El ritmo por clave, por espacio o por IP. | Sí, tras Retry-After. |
INTERNAL | 500 | Error interno. Un error nuestro: la referencia es el request_id. | Sí, con la misma Idempotency-Key. |
META_ERROR | 502 | WhatsApp no respondió como se esperaba. Meta caído, o un error al leer una plantilla o al subir un archivo (meta). | Sí. |
BUSY | 503 | El servidor está ocupado con otros archivos. El presupuesto de bytes en vuelo está lleno. | Sí, tras Retry-After. |
NOT_CONFIGURED | 503 | El número no puede enviar ahora. Número desconectado o sin credenciales. | No, hasta reconectarlo. |
STORAGE_UNAVAILABLE | 503 | No se pudo guardar el archivo. El almacén de archivos no respondió. | Sí. |
Por qué falló un mensaje
Un mensaje aceptado (202) puede fallar después. Entonces su status es failed y error.code dice por qué; si viene de WhatsApp, error.meta_code trae su código.
| error.code | Qué pasó |
|---|---|
expired | No salió dentro de su ttl. |
unknown_outcome | No se pudo confirmar si WhatsApp lo aceptó: revísalo antes de reenviar. |
workspace_inactive | El espacio se suspendió o se cerró con el mensaje en cola. |
number_unavailable | El número se desconectó con el mensaje en cola. |
number_blocked | El número no puede enviar (token, cuenta o pago). |
internal | Un error nuestro en la cola. |
window_closed | Pasaron más de 24 horas desde el último mensaje del contacto: hace falta una plantilla. |
recipient_unavailable | El destino no puede recibirlo: no tiene WhatsApp, usa una versión antigua o bloqueó al número. |
recipient_opted_out | El contacto dejó de recibir mensajes de marketing de este negocio. |
not_delivered_by_meta | WhatsApp decidió no entregarlo (límites de marketing por persona). |
media_rejected | WhatsApp no aceptó el archivo al enviarlo. |
template_invalid | La plantilla o sus datos no cuadran con lo que tiene WhatsApp (pausada, deshabilitada o con otro formato). |
payment_issue | Hay un problema de pago en la cuenta de WhatsApp Business. |
quality_limited | Límite por calidad o por spam del número. |
recipient_rate_limited | Demasiados mensajes al mismo destino en poco tiempo. |
meta_error | Otro error de WhatsApp: mira meta_code. |