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ódigoHTTPQué pasa¿Reintentar?
BAD_REQUEST400La petición está mal formada. JSON roto o cuerpo interrumpido.No: corrige la petición.
INVALID_CURSOR400El cursor no es válido. Manipulado, caducado, o de otra operación o de otros filtros.No: empieza de nuevo sin cursor.
API_KEY_EXPIRED401La 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_INVALID401La 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_REVOKED401La clave está revocada. La clave se revocó, o el espacio se cerró.No.
API_KEY_SUSPENDED401La clave está suspendida. Quien la creó salió del espacio, bajó de rol, perdió números o tiene la cuenta desactivada.No: rótala.
UNAUTHENTICATED401Falta la clave. La petición no lleva la cabecera Authorization.No.
FEATURE_NOT_ENABLED403Esa 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.
FORBIDDEN403No 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_SCOPE403La 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_ONLY403El espacio está en solo lectura. Una escritura con el espacio suspendido.No.
TEMPLATE_CATEGORY_NOT_ALLOWED403La 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_ALLOWED403Incluye 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_ALLOWED403La 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_FOUND404No existe. Lo ajeno o inexistente (mensaje, archivo, número, plantilla) y cualquier ruta desconocida.No.
METHOD_NOT_ALLOWED405Método no admitido. La ruta existe, pero no con ese método (Allow dice cuáles).No.
CONFLICT409Conflicto. El archivo todavía se está guardando.Sí, en unos segundos.
IDEMPOTENCY_IN_PROGRESS409Esa petición se está procesando. Otra petición con la misma Idempotency-Key está en curso.Sí, tras Retry-After.
MEDIA_NOT_READY409El 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_USED409El archivo ya se usó. Una subida sirve para un solo mensaje.No: súbelo otra vez.
WABA_IN_OTHER_WORKSPACE409La cuenta de WhatsApp Business está en otro espacio. Reservado: la v1 no conecta números.No.
WEBHOOK_LIMIT_REACHED409El 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_CONFLICT409El endpoint no admite eso en su estado. Editar o probar un endpoint suspendido.No: reactívalo en la consola.
MEDIA_UNAVAILABLE410El 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_EXPIRED410El archivo caducó. Pasaron más de 24 horas sin usarlo.No: súbelo otra vez.
LENGTH_REQUIRED411Falta el tamaño. Un multipart sin Content-Length.No.
PAYLOAD_TOO_LARGE413Demasiado grande. Un cuerpo JSON de más de 64 KB, o un archivo por encima de su límite.No.
UNSUPPORTED_MEDIA_TYPE415Tipo no admitido. El tipo de contenido de la petición, o el formato del archivo (reason).No.
RANGE_NOT_SATISFIABLE416El 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_REUSED422Esa clave de idempotencia ya se usó con otra petición. La misma Idempotency-Key con otro contenido.No: usa otra clave.
MEDIA_REJECTED422WhatsApp no aceptó el archivo. Meta lo rechazó al subirlo.No.
MESSAGE_NOT_INBOUND422Ese mensaje no llegó de un contacto. Marcar como leído un mensaje enviado: solo se marcan los que llegan.No.
TEMPLATE_NOT_FOUND422La plantilla no existe. El nombre o el idioma no están en la cuenta del número.No.
TEMPLATE_NOT_SENDABLE422La 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_FAILED422Los 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_UNKNOWN422Ese evento no existe. Un tipo que no está en el catálogo de eventos.No.
WEBHOOK_URL_INVALID422La 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_ALLOWED422Esa 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_UNRESOLVABLE422No encontramos ese dominio. El dominio de la URL no resuelve en el DNS.Sí, cuando esté publicado.
DAILY_LIMIT_REACHED429La 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_FULL429Hay demasiados mensajes esperando. 5.000 mensajes pendientes en el espacio.Sí, tras Retry-After.
RATE_LIMITED429Demasiadas peticiones. El ritmo por clave, por espacio o por IP.Sí, tras Retry-After.
INTERNAL500Error interno. Un error nuestro: la referencia es el request_id.Sí, con la misma Idempotency-Key.
META_ERROR502WhatsApp no respondió como se esperaba. Meta caído, o un error al leer una plantilla o al subir un archivo (meta).Sí.
BUSY503El servidor está ocupado con otros archivos. El presupuesto de bytes en vuelo está lleno.Sí, tras Retry-After.
NOT_CONFIGURED503El número no puede enviar ahora. Número desconectado o sin credenciales.No, hasta reconectarlo.
STORAGE_UNAVAILABLE503No 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.codeQué pasó
expiredNo salió dentro de su ttl.
unknown_outcomeNo se pudo confirmar si WhatsApp lo aceptó: revísalo antes de reenviar.
workspace_inactiveEl espacio se suspendió o se cerró con el mensaje en cola.
number_unavailableEl número se desconectó con el mensaje en cola.
number_blockedEl número no puede enviar (token, cuenta o pago).
internalUn error nuestro en la cola.
window_closedPasaron más de 24 horas desde el último mensaje del contacto: hace falta una plantilla.
recipient_unavailableEl destino no puede recibirlo: no tiene WhatsApp, usa una versión antigua o bloqueó al número.
recipient_opted_outEl contacto dejó de recibir mensajes de marketing de este negocio.
not_delivered_by_metaWhatsApp decidió no entregarlo (límites de marketing por persona).
media_rejectedWhatsApp no aceptó el archivo al enviarlo.
template_invalidLa plantilla o sus datos no cuadran con lo que tiene WhatsApp (pausada, deshabilitada o con otro formato).
payment_issueHay un problema de pago en la cuenta de WhatsApp Business.
quality_limitedLímite por calidad o por spam del número.
recipient_rate_limitedDemasiados mensajes al mismo destino en poco tiempo.
meta_errorOtro error de WhatsApp: mira meta_code.