API y SDK
Errores
El formato único de error de la API y el significado de cada código.
Formato del error
Sección titulada «Formato del error»Todo error de la API usa el mismo cuerpo JSON, con un code estable que puedes tratar en tu código. Este es el cuerpo real de una llamada a GET /v1/me sin clave:
HTTP/1.1 401 UnauthorizedContent-Type: application/jsonX-Request-Id: req_01a1c036cb127000b175ffba86a20018{ "error": { "code": "missing_api_key", "message": "Missing API key: send Authorization: Bearer <key>", "meta_code": null, "retryable": false, "request_id": "req_01a1c036cb127000b175ffba86a20018", "docs_url": "https://docs.messajo.com/errors#missing_api_key" }}| Campo | Tipo | Qué es |
|---|---|---|
code |
string | Código estable de Messajo. Trata el error por él, nunca por el mensaje. |
message |
string | Texto corto en inglés, útil para logs. Puede cambiar entre versiones. |
meta_code |
número o null |
Código original de Meta cuando el error vino de ella; null en los demás. |
retryable |
booleano | true cuando repetir la misma llamada puede funcionar. |
request_id |
string | Id de la solicitud, igual al encabezado X-Request-Id. |
docs_url |
string | Enlace al ancla del código en esta página. |
retry_after_ms |
número | Solo en los errores de límite (rate_limited, connection_rate_limited, pair_rate_limited, meta_rate_limited, link_locked): cuánto esperar, en milisegundos. |
details |
lista | Elementos { path, message }. En validation_failed, uno por campo inválido. En un error de Meta, details[0].message trae el detalle que mandó (error_data.details). En outside_service_window, el fin de la ventana (path: "window_ends_at"). |
Cuándo repetir
Sección titulada «Cuándo repetir»- Repite solo cuando
retryableseatrue. Los demás piden una corrección antes. - Si la respuesta trae
Retry-After(segundos) oretry_after_ms, espera al menos ese tiempo. - Sin
Retry-After, usa backoff exponencial con jitter (por ejemplo 1 s, 2 s, 4 s…) y un tope de intentos. - El envío de mensajes nunca se repite a ciegas: manda el encabezado
Idempotency-Keyy repite con la misma clave, para no entregar el mensaje dos veces. Mira Límites.
Códigos de Messajo
Sección titulada «Códigos de Messajo»Cada código tiene su propia ancla (/errors#<code>), la misma del docs_url.
validation_failed
- Estado HTTP
- 400
- Se puede repetir
- No
- Mensaje en el panel
- Algunos campos no son válidos. Revísalos e inténtalo de nuevo.
- Qué significa
- El cuerpo, la query o los parámetros de la solicitud no pasaron la validación.
- Qué hacer
- Lee
details: cada elemento trae elpathdel campo y el motivo. Corrige y envía de nuevo.
missing_api_key
- Estado HTTP
- 401
- Se puede repetir
- No
- Mensaje en el panel
- Envía la clave de API en el encabezado Authorization.
- Qué significa
- La solicitud llegó sin el encabezado
Authorization: Bearer. - Qué hacer
- Envía la clave en el encabezado
Authorization: Bearer <clave>. La cookie del panel no autentica la API; mira Autenticación.
invalid_api_key
- Estado HTTP
- 401
- Se puede repetir
- No
- Mensaje en el panel
- Clave de API no válida.
- Qué significa
- La clave enviada no existe o fue revocada.
- Qué hacer
- Revisa que copiaste la clave entera, sin espacios. Si fue revocada, crea otra en el panel.
api_key_expired
- Estado HTTP
- 401
- Se puede repetir
- No
- Mensaje en el panel
- Esta clave de API ha caducado.
- Qué significa
- La clave superó la fecha de vencimiento definida al crearla.
- Qué hacer
- Crea una clave nueva en el panel y cámbiala en tu integración antes de borrar la anterior.
api_key_disabled
- Estado HTTP
- 401
- Se puede repetir
- No
- Mensaje en el panel
- Esta clave de API está desactivada.
- Qué significa
- La clave existe, pero fue desactivada en el panel.
- Qué hacer
- Pide a un admin de la organización que reactive la clave o usa otra activa.
unauthenticated
- Estado HTTP
- 401
- Se puede repetir
- No
- Mensaje en el panel
- Tu sesión ha caducado. Inicia sesión de nuevo.
- Qué significa
- La ruta del panel exige una sesión y no existe o expiró.
- Qué hacer
- Vuelve a iniciar sesión en el panel. Las integraciones deben usar la API
/v1con clave.
billing_required
- Estado HTTP
- 402
- Se puede repetir
- No
- Mensaje en el panel
- Tu plan no permite esta acción. Revisa la facturación.
- Qué significa
- El plan de la organización no permite esta acción o hay un cobro pendiente.
- Qué hacer
- Revisa el plan y la facturación en el panel. Repetir la llamada no lo resuelve.
org_restricted
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- Esta organización está restringida: no se pueden crear elementos nuevos hasta regularizar.
- Qué significa
- La organización está restringida: no puede crear elementos nuevos (destinos, campañas, flows, plantillas, enlaces de conexión).
- Qué hacer
- Lo que ya existe sigue funcionando. Regulariza la situación de la organización en el panel; repetir la llamada no lo resuelve.
org_suspended
- Estado HTTP
- 402
- Se puede repetir
- No
- Mensaje en el panel
- Esta organización está suspendida. El panel queda solo de lectura hasta regularizar.
- Qué significa
- La organización está suspendida: la API solo responde a GET /v1/me y los webhooks quedan retenidos.
- Qué hacer
- Regulariza la situación de la organización en el panel. Al reactivarla, los webhooks retenidos se entregan en orden.
forbidden
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- No tienes permiso para hacer esto.
- Qué significa
- Quien hizo la llamada no tiene acceso a este recurso.
- Qué hacer
- Revisa que la clave o el usuario pertenezca a la organización dueña del recurso.
insufficient_permissions
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- Tu clave o tu rol no tiene este permiso.
- Qué significa
- La clave o el rol no tiene el permiso que exige la ruta.
- Qué hacer
- Crea una clave con el permiso necesario o pide un rol con más acceso.
connection_not_allowed
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- Esta clave no tiene acceso a esta conexión.
- Qué significa
- La clave está restringida a otras conexiones.
- Qué hacer
- Usa una clave habilitada para esta conexión o agrega la conexión a los permisos de la clave.
organization_key_required
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- Esta operación requiere una clave de la organización.
- Qué significa
- Esta operación solo acepta una clave de la organización (
mj_), y la clave usada es de conexión (mjc_). - Qué hacer
- Usa una clave de la organización y repite la llamada. Ver Autenticación.
two_factor_required
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- Tu rol exige verificación en dos pasos. Activa el 2FA para continuar.
- Qué significa
- Tu rol exige verificación en dos pasos y está desactivada. Solo aparece en el panel.
- Qué hacer
- Activa el 2FA en Perfil → Seguridad y repite la acción.
two_factor_mandatory
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- Los propietarios y admins no pueden desactivar la verificación en dos pasos.
- Qué significa
- Dueños y admins no pueden desactivar la verificación en dos pasos. Solo aparece en el panel.
- Qué hacer
- Mantén el 2FA activo o pide que cambien tu rol antes de desactivarlo.
no_active_organization
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Elige una organización para continuar.
- Qué significa
- La sesión del panel no tiene una organización elegida.
- Qué hacer
- Elige o crea una organización en el panel y repite la acción.
last_owner
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- La organización necesita al menos un propietario.
- Qué significa
- La acción dejaría la organización sin ningún dueño.
- Qué hacer
- Asciende a otro miembro a dueño antes de salir o de cambiar tu rol.
slug_taken
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Esta dirección ya está en uso. Elige otra.
- Qué significa
- Ya existe una organización con esta dirección.
- Qué hacer
- Elige otra dirección (slug) y envía de nuevo.
org_limit_reached
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Alcanzaste el límite de organizaciones por usuario.
- Qué significa
- Alcanzaste el límite de organizaciones por usuario.
- Qué hacer
- Elimina una organización que ya no uses o pide al administrador de la instancia que suba el límite.
reauth_failed
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- Contraseña o código de verificación incorrecto.
- Qué significa
- La contraseña o el código de verificación de la reconfirmación es incorrecto.
- Qué hacer
- Escribe de nuevo la contraseña y, si tienes 2FA, el código vigente de 6 dígitos.
account_delete_blocked
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Eres el único propietario de una organización con otros miembros. Transfiere la propiedad o elimínala antes.
- Qué significa
- Eres el único propietario de una organización con otros miembros.
- Qué hacer
- Transfiere la propiedad o elimina la organización y repite.
not_found
- Estado HTTP
- 404
- Se puede repetir
- No
- Mensaje en el panel
- No encontramos lo que buscabas.
- Qué significa
- El recurso no existe o no pertenece a la organización de la clave.
- Qué hacer
- Revisa el id y la organización. Un recurso de otra organización también responde 404.
conflict
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Este registro cambió o ya existe. Actualiza la página.
- Qué significa
- El registro cambió o ya existe con estos datos.
- Qué hacer
- Consulta el estado actual del recurso y decide si envías de nuevo.
rate_limited
- Estado HTTP
- 429
- Se puede repetir
- Sí
- Mensaje en el panel
- Demasiados intentos. Espera un poco e inténtalo de nuevo.
- Qué significa
- Superaste el límite de la clave o de la organización.
- Qué hacer
- Espera
retry_after_ms(o elRetry-After) y vuelve a intentar; mira Límites.
internal_error
- Estado HTTP
- 500
- Se puede repetir
- Sí
- Mensaje en el panel
- Algo salió mal de nuestro lado. Inténtalo de nuevo.
- Qué significa
- Algo falló de nuestro lado al procesar la solicitud.
- Qué hacer
- Repite con backoff. Si sigue, habla con soporte enviando el
request_id.
missing_signature
- Estado HTTP
- 401
- Se puede repetir
- No
- Mensaje en el panel
- El webhook llegó sin firma.
- Qué significa
- El webhook de entrada llegó sin el encabezado
X-Hub-Signature-256. - Qué hacer
- Solo Meta (o tu simulador) debe llamar a esta URL. Revisa que la llamada venga de la app correcta, firmada con su app secret.
invalid_signature
- Estado HTTP
- 401
- Se puede repetir
- No
- Mensaje en el panel
- La firma del webhook no coincide.
- Qué significa
- La firma
sha256=del webhook no coincide con el app secret configurado. - Qué hacer
- Revisa que
META_APP_SECRETsea el de la app que firma el webhook y que el cuerpo no se haya alterado en el camino.
invalid_payload
- Estado HTTP
- 400
- Se puede repetir
- No
- Mensaje en el panel
- El contenido del webhook no es válido.
- Qué significa
- El cuerpo del webhook no es un JSON con el formato que envía Meta.
- Qué hacer
- Envía el cuerpo tal como Meta lo generó, con
Content-Type: application/json.
payload_too_large
- Estado HTTP
- 413
- Se puede repetir
- No
- Mensaje en el panel
- El contenido enviado es demasiado grande.
- Qué significa
- El cuerpo de la solicitud superó el tamaño máximo aceptado.
- Qué hacer
- Reduce el contenido enviado. Los archivos grandes van como multimedia, no en el cuerpo.
channel_not_configured
- Estado HTTP
- 503
- Se puede repetir
- Sí
- Mensaje en el panel
- Este canal todavía no está configurado en el servidor.
- Qué significa
- El canal no tiene app secret configurado en este servidor, así que el webhook no se puede verificar.
- Qué hacer
- Meta reenvía lo que recibió
503.
idempotency_key_reused
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Esta Idempotency-Key ya se usó en otra solicitud.
- Qué significa
- La
Idempotency-Keyya se usó en las últimas 24 h con otro método, ruta o cuerpo. - Qué hacer
- Genera una clave nueva para cada operación distinta. Repite la misma clave solo para reenviar la misma solicitud.
idempotency_in_progress
- Estado HTTP
- 409
- Se puede repetir
- Sí
- Mensaje en el panel
- Una solicitud con esta Idempotency-Key todavía está en curso.
- Qué significa
- La primera solicitud con esta
Idempotency-Keytodavía se está procesando. - Qué hacer
- Espera unos segundos y repite con la misma clave: recibes la respuesta guardada.
destination_url_not_allowed
- Estado HTTP
- 400
- Se puede repetir
- No
- Mensaje en el panel
- Esta dirección de destino no está permitida.
- Qué significa
- La URL del destino apunta a una dirección bloqueada (red privada,
httpsin permiso, host inválido). - Qué hacer
- Lee
details[].messagecon el motivo y usa una URLhttpspública.
destination_limit_reached
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- La organización alcanzó el límite de destinos. Elimina uno para crear otro.
- Qué significa
- La organización ya tiene el número máximo de destinos.
- Qué hacer
- Elimina un destino que ya no uses antes de crear otro.
destination_paused
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Este destino está en pausa. Reanúdalo para continuar.
- Qué significa
- El destino está en pausa (por ti o por la pausa automática tras fallos seguidos).
- Qué hacer
- Corrige el endpoint, reanuda el destino en el panel y reenvía las entregas que fallaron.
outside_service_window
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Fuera de la ventana de 24 h de atención. Envía una plantilla.
- Qué significa
- El contacto no te escribe hace más de 24 h (72 h si vino de un anuncio), y solo una plantilla puede abrir la conversación.
- Qué hacer
- Envía una plantilla aprobada. Cuando el contacto responda, la ventana se abre de nuevo y vuelven los mensajes libres.
marketing_limit_reached
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Meta limitó los mensajes de marketing para este contacto.
- Qué significa
- Meta retuvo la plantilla de marketing para cuidar el engagement del contacto (límite por usuario).
- Qué hacer
- No reenvíes enseguida. Espera unos días o envía algo que el contacto pida; un reenvío inmediato no pasa.
pair_rate_limited
- Estado HTTP
- 429
- Se puede repetir
- Sí
- Mensaje en el panel
- Demasiados mensajes a este contacto en poco tiempo. Espera unos segundos.
- Qué significa
- Se alcanzó el límite por par de Meta (este número ↔ este contacto).
- Qué hacer
- Espera
retry_after_ms(6 s) antes de enviar de nuevo al mismo contacto. Los demás contactos no se ven afectados.
meta_rate_limited
- Estado HTTP
- 429
- Se puede repetir
- Sí
- Mensaje en el panel
- Meta limitó el caudal. Espera e inténtalo de nuevo.
- Qué significa
- Meta rechazó por el límite de caudal del número, la cuenta o la app, sin procesar la solicitud.
- Qué hacer
- Espera
retry_after_ms(o la cabeceraRetry-After) y repite. Mira Límites.
template_error
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Meta rechazó la plantilla. Mira el motivo en los detalles.
- Qué significa
- La plantilla no existe en ese idioma, los parámetros no coinciden, el texto supera el límite o está pausada/desactivada.
- Qué hacer
- Lee
details[].messageymeta_code. Revisa nombre, idioma y parámetros en Plantillas; una pausada o desactivada debe editarse.
policy_blocked
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- Meta bloqueó este número por una violación de política.
- Qué significa
- Meta restringió el número o la cuenta por violar las políticas de WhatsApp Business. La conexión queda
restricted. - Qué hacer
- Mira el motivo y el plazo en la salud de la conexión y en el Administrador de WhatsApp; apela allí si no estás de acuerdo.
connection_needs_reconnect
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- El acceso a esta conexión caducó. Reconecta el número.
- Qué significa
- El token de Meta fue revocado o caducó (contraseña cambiada, app eliminada, permiso retirado). La conexión queda
needs_reconnect. - Qué hacer
- Reconecta desde el panel o desde el enlace del correo que enviamos. Nada sale por esa conexión hasta reconectar.
meta_payment_required
- Estado HTTP
- 402
- Se puede repetir
- No
- Mensaje en el panel
- Hay un problema de pago en la cuenta de WhatsApp Business.
- Qué significa
- La cuenta de WhatsApp Business no tiene un método de pago válido, el pago falló o se agotó el crédito.
- Qué hacer
- Ajusta el método de pago en el Administrador comercial de Meta. Los mensajes los cobra Meta, no Messajo.
recipient_not_allowed
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Este número de prueba solo envía a destinatarios registrados.
- Qué significa
- El número de prueba de Meta solo envía a hasta 5 destinatarios registrados en la app.
- Qué hacer
- Registra el destinatario en el panel de la app de Meta o conecta un número real.
media_error
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Meta no pudo procesar el archivo multimedia.
- Qué significa
- Meta no descargó o no aceptó el archivo: tipo no soportado, archivo demasiado grande o enlace inaccesible.
- Qué hacer
- Lee
details[].message. Revisa tipos y tamaños aceptados y, si enviaste un enlace, que sea público y responda rápido.
number_not_registered
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Este número todavía no está registrado en la API de WhatsApp.
- Qué significa
- El registro del número en la Cloud API falló o se deshizo, así que Meta no acepta envíos desde él.
- Qué hacer
- Abre la conexión en el panel e intenta registrarla de nuevo. Si persiste, reconecta el número.
username_not_eligible
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Esta cuenta todavía no puede tener nombre de usuario en WhatsApp.
- Qué significa
- Meta todavía no habilitó nombres de usuario para esta cuenta de WhatsApp Business (Meta 147002). Aplica a las sugerencias y a definir el nombre.
- Qué hacer
- No hay nada que corregir en Messajo. Intenta de nuevo más tarde; la habilitación es de Meta y depende de la cuenta.
meta_invalid_parameter
- Estado HTTP
- 400
- Se puede repetir
- No
- Mensaje en el panel
- Meta rechazó un parámetro de la solicitud.
- Qué significa
- Algún campo del cuerpo enviado a Meta no es válido o no existe para este tipo de mensaje.
- Qué hacer
- Lee
details[].messageymeta_code, corrige el campo y envía de nuevo.
meta_unknown_outcome
- Estado HTTP
- 502
- Se puede repetir
- No
- Mensaje en el panel
- Meta no confirmó el envío. El mensaje pudo haber salido; revisa antes de reenviar.
- Qué significa
- Timeout o fallo temporal de Meta en un envío: no se sabe si el mensaje salió. Queda
queuedhasta que el estado llegue por webhook. - Qué hacer
- No reenvíes a ciegas. Confirma con el evento
message.statuso con el contacto; repetir con la mismaIdempotency-Keydevuelve el mismo 502 sin reenviar. Para enviar de nuevo a propósito, usa una clave nueva.
meta_error
- Estado HTTP
- 502
- Se puede repetir
- No
- Mensaje en el panel
- Meta devolvió un error.
- Qué significa
- Meta devolvió un error que Messajo todavía no traduce a un código propio.
- Qué hacer
- Lee
meta_codeydetails[].messagey busca el código en la documentación de Meta. Guarda elrequest_idsi abres un ticket.
connection_not_active
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Esta conexión no está activa.
- Qué significa
- Obsoleto: sustituido por
connection_pending,connection_disconnected,connection_restricted,connection_disabledyconnection_needs_reconnect; se elimina en la próxima versión mayor. Hoy solo sale cuando la organización no tiene ninguna cuenta activa para la acción. - Qué hacer
- Mira el estado de la conexión en el panel y resuelve el motivo (reconectar, terminar el registro o esperar a que termine la restricción).
connection_restricted
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- La conexión está restringida por Meta.
- Qué significa
- Meta restringió la conexión y el envío está bloqueado.
- Qué hacer
- Mira el motivo en la conexión, en el panel, y espera a que termine la restricción o resuélvela en Meta.
connection_disabled
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- La conexión fue desactivada por Meta.
- Qué significa
- Meta desactivó la conexión.
- Qué hacer
- Revisa el estado en la conexión, en el panel, y abre una apelación en Meta si la desactivación es indebida.
connection_disconnected
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- La conexión está desconectada. Reconéctala para usarla.
- Qué significa
- La conexión está desconectada y no envía.
- Qué hacer
- Reconecta la conexión en el panel.
connection_pending
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- La configuración de la conexión aún no terminó.
- Qué significa
- La configuración de la conexión aún no terminó.
- Qué hacer
- Termina el registro de la conexión en el panel antes de enviar.
pin_invalid
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- PIN de verificación en dos pasos incorrecto.
- Qué significa
- El PIN de la verificación en dos pasos es incorrecto.
- Qué hacer
- Informa el PIN correcto del número. Si lo olvidaste, restablécelo en la app de WhatsApp.
pin_attempts_exhausted
- Estado HTTP
- 429
- Se puede repetir
- Sí
- Mensaje en el panel
- Demasiados intentos para este número. Inténtalo más tarde.
- Qué significa
- El número alcanzó el límite de intentos de registro.
- Qué hacer
- Espera el tiempo indicado en
retry_after_msantes de intentar de nuevo.
secret_rotation_pending
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- El secreto anterior sigue vigente. Espera a que expire para rotarlo de nuevo.
- Qué significa
- El secreto anterior del destino sigue vigente.
- Qué hacer
- Espera a que expire el secreto anterior para rotarlo de nuevo.
notification_type_locked
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Este aviso es obligatorio y no se puede cambiar.
- Qué significa
- El tipo de aviso es obligatorio y no admite cambios.
- Qué hacer
- Elige otro tipo de aviso; los de seguridad y de cuenta siempre se envían.
connection_rate_limited
- Estado HTTP
- 429
- Se puede repetir
- Sí
- Mensaje en el panel
- Esta conexión alcanzó su velocidad máxima de envío. Espera un momento.
- Qué significa
- El número ya envía a la velocidad máxima que Meta le permite (20/s en coexistencia, 80/s o más solo API).
- Qué hacer
- Espera
retry_after_msy repite. Nada queda en cola: tu integración repite. Mira Límites.
account_flagged
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- Esta cuenta de WhatsApp Business fue bloqueada o marcada por Meta.
- Qué significa
- Meta bloqueó o marcó esta cuenta de WhatsApp Business por una violación, y no se puede conectar.
- Qué hacer
- Resuélvelo con Meta en el Administrador de WhatsApp. Cuando se libere, conecta de nuevo.
signup_code_invalid
- Estado HTTP
- 400
- Se puede repetir
- No
- Mensaje en el panel
- El código del registro caducó o no es válido. Abre la ventana de Meta de nuevo.
- Qué significa
- El
codeque devuelve la ventana de Meta vale 30 s y una sola vez; caducó o ya se usó. - Qué hacer
- Vuelve a empezar la conexión y termina sin pausa después de que se cierre la ventana de Meta.
signup_scope_mismatch
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- Faltaron permisos en la ventana de Meta. Conecta de nuevo y acepta todos.
- Qué significa
- La ventana de Meta terminó sin los permisos para administrar y enviar mensajes con la cuenta de WhatsApp Business.
- Qué hacer
- Conecta de nuevo y deja marcados todos los permisos en la ventana de Meta.
signup_session_expired
- Estado HTTP
- 410
- Se puede repetir
- No
- Mensaje en el panel
- La sesión de registro caducó. Empieza de nuevo.
- Qué significa
- La sesión de conexión dura 30 minutos y se agotó, o fue cancelada.
- Qué hacer
- Empieza la conexión de nuevo desde el panel o el enlace de conexión.
signup_incomplete
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- El registro terminó sin un número de teléfono. Termínalo eligiendo un número.
- Qué significa
- La ventana de Meta creó o eligió la cuenta de WhatsApp Business, pero no terminó con exactamente un número.
- Qué hacer
- Conecta de nuevo y elige (o registra) el número en la ventana de Meta hasta el final.
system_user_assignment_failed
- Estado HTTP
- 502
- Se puede repetir
- No
- Mensaje en el panel
- Este servidor no pudo obtener acceso a la cuenta de WhatsApp. Pide al administrador de la instancia que revise el usuario del sistema de Meta.
- Qué significa
- Meta rechazó asignar el usuario del sistema de la instancia (
META_SYSTEM_USER_TOKEN) a la cuenta de WhatsApp Business, o su token no ve la cuenta. - Qué hacer
- Quien administra la instancia revisa el token y el id del usuario del sistema (debe ser admin del portfolio) y la cuenta conecta de nuevo. No se guardó nada.
connection_already_exists
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Este número ya está conectado.
- Qué significa
- El número ya tiene una conexión activa, en esta organización o en otra.
- Qué hacer
- Usa la conexión existente. Para cambiarla de organización, desconéctala allí primero.
waba_owned_by_other_org
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Esta cuenta de WhatsApp Business ya está conectada a otra organización.
- Qué significa
- La cuenta de WhatsApp Business (WABA) ya está conectada a otra organización.
- Qué hacer
- Desconecta la cuenta en la otra organización primero, o usa la organización que ya la tiene.
invitation_invalid
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Esta invitación ya no es válida. Pide una nueva.
- Qué significa
- Quien envió la invitación salió de la organización o ya no puede conceder ese rol.
- Qué hacer
- Pide a un administrador de la organización que envíe una nueva invitación.
reconnect_mismatch
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- La reconexión se hizo con otro número. Elige el mismo número de la conexión.
- Qué significa
- En la reconexión, la ventana de Meta devolvió un número o cuenta distinto del de la conexión original.
- Qué hacer
- Reconecta eligiendo el mismo número. Para un número nuevo, crea una conexión nueva.
coex_not_on_business_app
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- El modo coexistencia exige un número que ya use la app WhatsApp Business.
- Qué significa
- En el modo coexistencia el número sigue en la app WhatsApp Business del celular; este número no está en ella.
- Qué hacer
- Instala y activa el número en la app WhatsApp Business, o conéctalo en modo solo API.
link_invalid
- Estado HTTP
- 404
- Se puede repetir
- No
- Mensaje en el panel
- Este enlace de conexión no existe.
- Qué significa
- La dirección del enlace está incompleta, mal escrita o el enlace fue revocado.
- Qué hacer
- Pide un enlace nuevo a quien te lo envió.
link_expired
- Estado HTTP
- 410
- Se puede repetir
- No
- Mensaje en el panel
- Este enlace de conexión caducó.
- Qué significa
- El enlace pasó su fecha de caducidad (30 días como máximo).
- Qué hacer
- Pide un enlace nuevo a quien te lo envió.
link_used
- Estado HTTP
- 410
- Se puede repetir
- No
- Mensaje en el panel
- Este enlace de conexión ya se usó.
- Qué significa
- El enlace es de un solo uso y ya conectó un número.
- Qué hacer
- Si necesitas conectar otro número, pide un enlace nuevo.
link_locked
- Estado HTTP
- 423
- Se puede repetir
- Sí
- Mensaje en el panel
- Demasiados intentos de contraseña. Este enlace quedó bloqueado unos minutos.
- Qué significa
- Demasiadas contraseñas incorrectas seguidas bloquearon el enlace por un tiempo.
- Qué hacer
- Espera
retry_after_mse inténtalo de nuevo con la contraseña correcta.
link_password_required
- Estado HTTP
- 401
- Se puede repetir
- No
- Mensaje en el panel
- Este enlace pide contraseña.
- Qué significa
- Quien creó el enlace definió una contraseña para abrirlo.
- Qué hacer
- Escribe la contraseña que vino con el enlace. Sin ella, pídela a quien lo envió.
link_password_invalid
- Estado HTTP
- 401
- Se puede repetir
- No
- Mensaje en el panel
- Contraseña incorrecta.
- Qué significa
- La contraseña escrita no coincide con la del enlace.
- Qué hacer
- Revisa la contraseña e inténtalo de nuevo. Varios intentos fallidos bloquean el enlace unos minutos.
mirror_path_blocked
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- Messajo bloquea esta ruta de la API de Meta.
- Qué significa
- La llamada por la capa espejo rompería la conexión (p. ej.: desregistrar el número, cambiar la suscripción de la app) y está bloqueada.
- Qué hacer
- Hazlo desde el panel o la ruta propia de Messajo, que mantiene la conexión coherente.
media_too_large
- Estado HTTP
- 413
- Se puede repetir
- No
- Mensaje en el panel
- El archivo es demasiado grande para este tipo de contenido.
- Qué significa
- El archivo supera el límite de Meta para su tipo (p. ej.: 16 MB para audio y video, 5 MB para imagen, 100 MB para documento).
- Qué hacer
- Comprime el archivo o envíalo como documento, que acepta más.
media_type_not_supported
- Estado HTTP
- 415
- Se puede repetir
- No
- Mensaje en el panel
- Este tipo de archivo no es compatible.
- Qué significa
- El tipo del archivo (MIME) no está entre los que WhatsApp acepta para ese tipo de mensaje.
- Qué hacer
- Conviértelo a un formato aceptado (p. ej.: JPEG/PNG, MP4, OGG/Opus, PDF) o envíalo como documento.
voice_conversion_failed
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- No se pudo convertir el audio en mensaje de voz.
- Qué significa
- La conversión del audio a OGG/Opus (mensaje de voz) falló: archivo dañado o formato que el conversor no lee.
- Qué hacer
- Envía el audio ya en OGG/Opus, o como audio común sin
voice.
template_not_found
- Estado HTTP
- 404
- Se puede repetir
- No
- Mensaje en el panel
- Plantilla no encontrada.
- Qué significa
- No hay plantilla con ese id, o con ese nombre e idioma, en esta cuenta de WhatsApp Business.
- Qué hacer
- Revisa nombre e idioma en Plantillas, o sincroniza la lista con Meta.
coex_not_supported
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- No disponible en números de coexistencia: cámbialo en la app WhatsApp Business.
- Qué significa
- Número en coexistencia: Meta no deja que la API cambie el perfil, el nombre visible ni el username; eso se hace en la app WhatsApp Business del teléfono.
- Qué hacer
- Cámbialo en la app WhatsApp Business del teléfono conectado, o usa un número solo API.
instagram_account_not_professional
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- No se concedió ninguna cuenta profesional de Instagram en el inicio de sesión. Selecciona la cuenta en la pantalla de Meta (debe ser profesional) e inténtalo de nuevo.
- Qué significa
- No se concedió ninguna cuenta profesional en el inicio de sesión de Instagram; Meta solo abre las API de mensajes y contenido a cuentas profesionales.
- Qué hacer
- En la pantalla de Meta, selecciona la cuenta y comprueba que sea profesional y administrada por la persona que inició sesión; luego conéctala de nuevo.
instagram_scope_missing
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- Falta un permiso de Instagram para esta función. Vuelve a conectar la cuenta y acepta todos los permisos.
- Qué significa
- La conexión se hizo sin el permiso que esta función exige (comentarios, publicación o insights).
details[0].messagetrae el permiso que falta. - Qué hacer
- Vuelve a conectar la cuenta de Instagram y deja marcados todos los permisos en la ventana de Meta.
oauth_state_invalid
- Estado HTTP
- 400
- Se puede repetir
- No
- Mensaje en el panel
- No pudimos confirmar la conexión. Empieza de nuevo desde el botón de conectar.
- Qué significa
- El retorno del inicio de sesión de Meta trajo un
stateque no coincide con la sesión de conexión abierta (alterado, vencido o de otra pestaña). - Qué hacer
- Empieza la conexión de nuevo desde el panel o el enlace de conexión, en la misma pestaña, sin reutilizar direcciones antiguas.
messenger_no_pages
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Ninguna Página de Facebook disponible para conectar. Revisa que administres la Página y que la elegiste en la ventana de Meta.
- Qué significa
- Ninguna Página elegida en el inicio de sesión de Facebook se puede conectar: le faltan las tareas de mensajes/administrar o ya está conectada en otra organización.
- Qué hacer
- Revisa que tengas acceso total a la Página (tareas
MESSAGINGoMANAGE), que la marcaste en la ventana de Meta y que no esté vinculada a otra organización.
messenger_page_not_granted
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- Esta Página no se autorizó en el inicio de sesión de Facebook. Conecta de nuevo y marca la Página.
- Qué significa
- La Página elegida no está entre las autorizadas en la ventana del inicio de sesión de Facebook.
- Qué hacer
- Elige una Página de la lista devuelta o inicia sesión de nuevo marcando la Página que falta.
type_not_supported_by_channel
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Este tipo de contenido no existe en este canal.
- Qué significa
- El
type(o campo de perfil) enviado no existe en el canal de la conexión, comotemplateen Instagram ocardsen WhatsApp. - Qué hacer
- Consulta los tipos aceptados por canal en la referencia de la API y elige uno equivalente.
tag_not_supported_by_channel
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Este canal no acepta etiquetas de mensaje.
- Qué significa
- El envío trajo
tag(comohuman_agent) en una conexión cuyo canal no tiene etiquetas, como WhatsApp. - Qué hacer
- Quita el
tag. En WhatsApp, fuera de la ventana de 24 h, envía una plantilla.
human_agent_window_closed
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Pasaron más de 7 días desde el último mensaje del contacto. Espera a que escriba de nuevo.
- Qué significa
- La etiqueta
human_agentsolo vale hasta 7 días después del último mensaje del contacto, y ese plazo pasó. - Qué hacer
- No se puede enviar hasta que el contacto escriba de nuevo.
detailsdice cuándo se cerró la ventana.
human_agent_not_approved
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- La app aún no tiene aprobación de Meta para responder como agente humano.
- Qué significa
- Meta rechazó el envío con
human_agent: la app no tiene la función Human Agent aprobada en App Review. - Qué hacer
- Pide la función Human Agent en el App Review de la app de Meta. Mientras tanto, responde dentro de la ventana de 24 h.
meta_permission_denied
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- Meta negó el permiso para esta acción. Vuelve a conectar la cuenta y acepta todos los permisos.
- Qué significa
- Meta rechazó la llamada por falta de permiso: se retiró un permiso, se quitó el rol en la Página o la función aún no está aprobada en la app.
- Qué hacer
- Revisa la salud de la conexión en el panel. Vuelve a conectar aceptando todos los permisos; si sigue, revisa el App Review de la app de Meta.
private_reply_window_closed
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Se acabó el plazo para responder este comentario por Direct.
- Qué significa
- La respuesta privada solo se puede enviar hasta 7 días después del comentario (en comentario de live, solo durante el live).
- Qué hacer
- Responde en público al comentario o espera a que el contacto te escriba por Direct.
private_reply_already_sent
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Este comentario ya recibió una respuesta por Direct.
- Qué significa
- Meta permite una sola respuesta privada por comentario, y ya se envió.
- Qué hacer
- Sigue la conversación en el Direct que abrió la respuesta privada.
comment_not_found
- Estado HTTP
- 404
- Se puede repetir
- No
- Mensaje en el panel
- Comentario no encontrado.
- Qué significa
- No hay comentario con ese id en esta conexión, o fue eliminado.
- Qué hacer
- Revisa el id en la lista de comentarios del post o en los eventos
comment.*.
comment_not_owned
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- Solo se pueden eliminar comentarios en los posts de esta cuenta.
- Qué significa
- El comentario está en una publicación de otra cuenta (por ejemplo, una mención), y Meta solo deja eliminar comentarios en los posts propios.
- Qué hacer
- Oculta o responde el comentario, o pide al dueño del post que lo elimine.
publication_not_editable
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Esta publicación ya está en curso y ya no se puede cambiar.
- Qué significa
- Solo las publicaciones programadas (
scheduled) o en cola (queued) se pueden editar o cancelar; esta ya se está creando, publicando o terminó. - Qué hacer
- Sigue el
statusde la publicación. Si falló, usa reintentar; si ya salió, edita o elimina el post en Instagram.
publication_media_invalid
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Se rechazó el medio de la publicación. Revisa formato, tamaño y duración.
- Qué significa
- Meta no pudo procesar el medio de la publicación (contenedor en
ERROR) o está fuera de las reglas: imagen JPEG hasta 8 MiB, video MP4/MOV hasta 300 MiB (story hasta 100 MiB). - Qué hacer
- Lee
details, que trae elstatusde Meta, ajusta el archivo y crea la publicación de nuevo.
media_url_not_public
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Meta no puede descargar el medio: la dirección no es pública.
- Qué significa
- Para publicar, Meta descarga el medio desde la URL, y la dirección enviada (o la del almacenamiento) no es accesible desde internet.
- Qué hacer
- Usa una URL pública en HTTPS.
media_url_expired
- Estado HTTP
- 410
- Se puede repetir
- No
- Mensaje en el panel
- El enlace de este medio venció y ya no se puede descargar.
- Qué significa
- La URL firmada del adjunto venció antes de la descarga, y Meta no emite otra.
- Qué hacer
- Pide al contacto que envíe el archivo de nuevo.
publishing_limit_reached
- Estado HTTP
- 429
- Se puede repetir
- Sí
- Mensaje en el panel
- La cuenta llegó al límite de publicaciones de las últimas 24 horas. Intenta más tarde.
- Qué significa
- La cuenta de Instagram alcanzó el límite de publicaciones por API de las últimas 24 horas (
content_publishing_limit). - Qué hacer
- Espera el tiempo de
retry_after_mso prográmala para más tarde. Las publicaciones en cola se aplazan solas hasta 24 h.
container_timeout
- Estado HTTP
- 504
- Se puede repetir
- No
- Mensaje en el panel
- Meta tardó demasiado en procesar el medio. Intenta publicar de nuevo.
- Qué significa
- El contenedor de la publicación quedó en procesamiento en Meta más de 30 minutos.
- Qué hacer
- Reintenta la publicación. Si se repite, reduce el tamaño o la duración del video.
insights_not_available
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- No hay insights disponibles para este elemento.
- Qué significa
- Meta no ofrece insights para este elemento: hijo de carrusel, story vencido sin snapshot, post antiguo o cuenta por debajo del mínimo de seguidores.
- Qué hacer
- Consulta el post padre del carrusel o un período más reciente. Los datos de Meta pueden tardar hasta 48 h.
welcome_flow_in_use
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Este flujo de bienvenida está en uso en un anuncio y no se puede cambiar.
- Qué significa
- El flujo de bienvenida está vinculado a un anuncio activo, y Meta no deja cambiarlo ni eliminarlo.
- Qué hacer
- Quita el flujo del anuncio en el Administrador de anuncios o crea un flujo nuevo.
signed_request_invalid
- Estado HTTP
- 400
- Se puede repetir
- No
- Mensaje en el panel
- La solicitud de Meta llegó con una firma inválida.
- Qué significa
- El callback de desautorización o de eliminación de datos llegó sin
signed_request, con una firma que no coincide con el secreto de la app o con un algoritmo distinto deHMAC-SHA256. - Qué hacer
- Revisa que la URL del callback en la app de Meta apunte a este servidor y que
META_APP_SECRETsea de la misma app.
data_deletion_not_found
- Estado HTTP
- 404
- Se puede repetir
- No
- Mensaje en el panel
- No encontramos una solicitud de eliminación con este código.
- Qué significa
- No hay solicitud de eliminación de datos con ese código de confirmación, o pasó de 1 año y se eliminó.
- Qué hacer
- Revisa el código que Meta mostró al pedir la eliminación y copia la dirección completa.
invalid_cursor
- Estado HTTP
- 400
- Se puede repetir
- No
- Mensaje en el panel
- El cursor de paginación no es válido. Vuelve a empezar desde la primera página.
- Qué significa
- El
cursorenviado no lo generó esta ruta con estos mismos filtros, o fue modificado. - Qué hacer
- Envía el
next_cursortal como vino en la respuesta anterior, con los mismos filtros. Para empezar de nuevo, omite elcursor.
retention_out_of_range
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Elige una retención entre 7 días y el máximo de esta instancia.
- Qué significa
- El plazo de retención pedido es menor que 7 días o mayor que el máximo de la instancia (
RETENTION_MAX_DAYS). - Qué hacer
- Elige un valor dentro del rango indicado en la configuración de datos de la organización.
campaign_channel_not_supported
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Las campañas solo están disponibles en conexiones de WhatsApp.
- Qué significa
- La conexión elegida es de un canal sin envío masivo. Meta solo permite campañas con plantilla en WhatsApp.
- Qué hacer
- Elige una conexión de WhatsApp en
connection_id.
campaign_template_not_approved
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- La plantilla debe estar aprobada y ser de marketing o de utilidad.
- Qué significa
- La plantilla no está
APPROVEDen Meta o su categoría no se usa en campañas (soloMARKETINGyUTILITY). - Qué hacer
- Espera la aprobación o elige otra plantilla. Sincroniza las plantillas de la conexión si el estado cambió en Meta hace poco.
campaign_template_mapping_invalid
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- El mapeo de variables no cubre todos los parámetros de la plantilla.
- Qué significa
- Algún parámetro de la plantilla (encabezado, cuerpo o botón) quedó sin fuente en
variable_mapping, o la fuente no sirve para ese parámetro. - Qué hacer
- Lee
details: cada ítem trae elpathdel parámetro y el motivo. Asígnale una columna, un valor fijo o el nombre del contacto.
campaign_not_editable
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Esta campaña ya no se puede editar en su estado actual.
- Qué significa
- Plantilla, mapeo y destinatarios solo cambian en
draft. Nombre y velocidad también cambian enscheduled,pausedyauto_paused. - Qué hacer
- Desprograma la campaña para volver a
draft, o crea una campaña nueva.
campaign_invalid_state
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Esta acción no es posible en el estado actual de la campaña.
- Qué significa
- La acción pedida (programar, iniciar, pausar, reanudar, cancelar) no vale desde el
statusactual de la campaña. - Qué hacer
- Consulta la campaña, revisa el
statusy elige una acción permitida desde él.
campaign_no_recipients
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- La campaña no tiene ningún destinatario válido.
- Qué significa
- La campaña no tiene ningún destinatario en
pending: la lista está vacía o todas las filas quedaroninvalid. - Qué hacer
- Importa destinatarios y corrige las filas inválidas (el informe de la importación muestra fila, columna y motivo).
campaign_too_many_recipients
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- La lista supera el límite de destinatarios de la campaña.
- Qué significa
- La importación superaría el máximo de 100 000 destinatarios por campaña, o la llamada inline trajo más de 10 000 filas.
- Qué hacer
- Divide la lista en más de una campaña, o envía un archivo CSV/JSON en lugar de la lista inline.
campaign_import_in_progress
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Todavía hay una importación de destinatarios en curso.
- Qué significa
- Un archivo de destinatarios todavía se está procesando, y la campaña no puede programarse, iniciarse ni recibir otra importación hasta que termine.
- Qué hacer
- Sigue la importación hasta
completedofailedy vuelve a intentarlo.
campaign_schedule_invalid
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Programa entre 1 minuto y 90 días a partir de ahora.
- Qué significa
- El
scheduled_atestá en el pasado, a menos de 1 minuto de ahora o a más de 90 días. - Qué hacer
- Envía una hora en ISO 8601 con zona horaria dentro de ese rango. Para enviar ya, inicia la campaña en lugar de programarla.
spend_cap_reached
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Se alcanzó el tope de gasto del mes. Las campañas quedan bloqueadas hasta el próximo mes o hasta que subas el tope.
- Qué significa
- La organización alcanzó su tope de gasto mensual con "pausar campañas" activado, así que las campañas no se pueden iniciar ni reanudar.
- Qué hacer
- Sube el tope en Configuración > Costos, desactiva "pausar campañas" o espera al próximo mes.
meta_spam_rate_limited
- Estado HTTP
- 429
- Se puede repetir
- No
- Mensaje en el panel
- Meta limitó el número por exceso de denuncias o bloqueos.
- Qué significa
- Meta rechazó el envío (código 131048) porque muchos mensajes de este número fueron denunciados o bloqueados. Las campañas se pausan solas con este error.
- Qué hacer
- No reenvíes. Revisa la lista (solo quien pidió recibir), el contenido de la plantilla y la frecuencia; espera a que la calidad del número se recupere antes de reanudar.
destination_type_disabled
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Este tipo de destino está desactivado en este servidor.
- Qué significa
- El servidor no activa este tipo de destino (RabbitMQ, SQS, Kafka o WebSocket). Los destinos ya creados de este tipo quedan pausados.
- Qué hacer
- Usa un webhook, o pide a quien opera la instancia que active
DESTINATIONS_<TIPO>_ENABLED.
no_client_connected
- Estado HTTP
- 503
- Se puede repetir
- Sí
- Mensaje en el panel
- Ningún cliente WebSocket está conectado a este destino.
- Qué significa
- La entrega al destino WebSocket no encontró ningún cliente conectado (o ninguno confirmó la recepción). Solo aparece como último error de la entrega.
- Qué hacer
- Mantén un cliente conectado en
/v1/wscon un ticket válido; la entrega se reintenta y, tras los intentos, va a la lista de fallos.
ws_ticket_invalid
- Estado HTTP
- 401
- Se puede repetir
- No
- Mensaje en el panel
- El ticket del WebSocket no es válido, venció o ya se usó.
- Qué significa
- El ticket enviado al abrir
/v1/wsno existe, ya venció o ya se usó: cada ticket sirve para una sola conexión. - Qué hacer
- Pide un ticket nuevo por la API justo antes de conectar y úsalo una sola vez.
ws_session_limit
- Estado HTTP
- 429
- Se puede repetir
- No
- Mensaje en el panel
- Hay demasiadas sesiones WebSocket abiertas para este destino.
- Qué significa
- El destino ya tiene el máximo de sesiones WebSocket simultáneas.
- Qué hacer
- Cierra las conexiones que ya no usas (o reutiliza una) antes de abrir otra.
data_request_in_progress
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Ya hay una solicitud de este tipo en curso.
- Qué significa
- La organización ya tiene una solicitud de exportación o eliminación de este tipo en cola o en ejecución.
- Qué hacer
- Sigue la solicitud en la configuración de datos de la organización y espera a que termine.
data_request_limit
- Estado HTTP
- 429
- Se puede repetir
- Sí
- Mensaje en el panel
- Se alcanzó el límite de exportaciones de las últimas 24 horas.
- Qué significa
- La organización ya pidió 3 exportaciones en las últimas 24 horas.
- Qué hacer
- Descarga una de las exportaciones ya listas o vuelve a intentarlo después del tiempo indicado en
retry_after_ms.
data_export_expired
- Estado HTTP
- 410
- Se puede repetir
- No
- Mensaje en el panel
- Esta exportación venció y el archivo se eliminó.
- Qué significa
- El archivo de la exportación queda disponible por 7 días; después se elimina.
- Qué hacer
- Pide una nueva exportación en la configuración de datos de la organización.
calling_not_supported_in_coex
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Las llamadas no están disponibles para números en coexistencia con la app WhatsApp Business.
- Qué significa
- El número está en coexistencia con la app WhatsApp Business y Meta no ofrece la Calling API en ese modo.
- Qué hacer
- Usa un número conectado solo por la API (sin la app) para recibir y hacer llamadas.
calling_not_enabled
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Las llamadas no están activadas en este número.
- Qué significa
- Las llamadas están desactivadas en la configuración del número.
- Qué hacer
- Activa las llamadas con
PUT /v1/connections/{id}/calling-settings(status: ENABLED) o en la configuración de llamadas de la conexión en el panel.
call_not_found
- Estado HTTP
- 404
- Se puede repetir
- No
- Mensaje en el panel
- Llamada no encontrada.
- Qué significa
- La llamada no existe en esta organización.
- Qué hacer
- Revisa el
id(cal_…) y si la clave tiene acceso a la conexión de la llamada.
call_invalid_state
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Esta acción no está permitida en el estado actual de la llamada.
- Qué significa
- La acción no es válida en el estado actual de la llamada (p. ej., aceptar una llamada ya finalizada).
- Qué hacer
- Lee el estado actual en
detailso enGET /v1/calls/{id}y envía solo las acciones que ese estado permite.
call_sdp_invalid
- Estado HTTP
- 400
- Se puede repetir
- No
- Mensaje en el panel
- SDP no válido.
- Qué significa
- El SDP llegó vacío, supera 64 KiB o no empieza con
v=0. - Qué hacer
- Envía el SDP generado por tu pila WebRTC sin cambios.
call_sdp_mismatch
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- El SDP debe ser el mismo enviado en pre_accept.
- Qué significa
- Después de
pre_accept, Meta exige queacceptuse exactamente el mismo SDP. - Qué hacer
- Guarda el SDP del
pre_accepty reenvía el mismo texto enaccept.
call_permission_required
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- El contacto aún no dio permiso para recibir llamadas.
- Qué significa
- El contacto no dio permiso a la empresa para llamar (Meta 138006).
- Qué hacer
- Pide el permiso con un mensaje
interactive.call_permission_request(o una plantilla con ese botón) y espera el eventocall.permission_updated.
call_rate_limited
- Estado HTTP
- 429
- Se puede repetir
- No
- Mensaje en el panel
- Se alcanzó el límite de llamadas de Meta.
- Qué significa
- Meta limitó las llamadas de este número o a este contacto.
- Qué hacer
- Espera antes de volver a llamar; no reintentes en bucle.
call_error
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Meta rechazó la solicitud de llamada.
- Qué significa
- Meta rechazó la solicitud de la Calling API con un código 138xxx.
- Qué hacer
- Lee
meta_codeydetails[0].messagepara ver el motivo; corrige la solicitud antes de reintentar.
group_not_supported
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Los grupos no están disponibles para este número.
- Qué significa
- Este número no tiene acceso a la Groups API (p. ej., un número en coexistencia).
- Qué hacer
- Usa un número conectado solo por la API y apto para grupos.
group_not_found
- Estado HTTP
- 404
- Se puede repetir
- No
- Mensaje en el panel
- Grupo no encontrado.
- Qué significa
- El grupo no existe en esta organización.
- Qué hacer
- Revisa el
id(grp_…) y si la clave tiene acceso a la conexión del grupo.
group_not_active
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- El grupo no está activo.
- Qué significa
- El grupo aún se está creando, fue suspendido o eliminado.
- Qué hacer
- Espera el evento
group.createdantes de enviar; un grupo suspendido o eliminado no recibe mensajes.
group_participant_limit
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Demasiados participantes para un grupo.
- Qué significa
- El grupo superaría el límite de participantes (8).
- Qué hacer
- Elimina participantes antes de invitar a otros.
group_message_type_not_supported
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Este tipo de mensaje no se puede enviar a un grupo.
- Qué significa
- Meta solo acepta texto, medios y plantillas de texto o medios en grupos.
- Qué hacer
- Envía uno de esos tipos; botones, listas y Flows no van a un grupo.
flow_not_found
- Estado HTTP
- 404
- Se puede repetir
- No
- Mensaje en el panel
- Flow no encontrado.
- Qué significa
- El Flow no existe en esta organización.
- Qué hacer
- Revisa el
id(flw_…) o el id de Meta del Flow.
flow_not_editable
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- El Flow solo se puede editar mientras está en borrador.
- Qué significa
- El JSON solo cambia mientras el Flow está en
DRAFT. - Qué hacer
- Clona el Flow publicado (
POST /v1/flows/{id}/clone) y edita la copia.
flow_invalid_json
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- El JSON del Flow no es válido.
- Qué significa
- El JSON del Flow no pasó la validación (local o de Meta, código 139001).
- Qué hacer
- Cada elemento de
detailstraepath = flow_json:<línea>:<columna>y el motivo; corrige y vuelve a subirlo.
flow_handler_required
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Este Flow necesita un servidor de intercambio de datos.
- Qué significa
- El Flow usa el endpoint de Messajo, pero falta el servidor del cliente (handler) o la base pública HTTPS del endpoint.
- Qué hacer
- Configura
endpoint.url(HTTPS público) en el Flow; quien opera la instancia necesitaFLOWS_ENDPOINT_BASE_URLconhttps:.
flow_key_not_uploaded
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- La clave de cifrado del Flow aún no se envió a un número activo.
- Qué significa
- La clave pública de los Flows aún no se envió a ningún número activo de la cuenta; Meta no puede llamar al endpoint.
- Qué hacer
- Espera la sincronización de la clave o rótala con
POST /v1/connections/{id}/flow-key/rotatey vuelve a publicar.
flow_error
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Meta rechazó la solicitud del Flow.
- Qué significa
- Meta rechazó la solicitud de Flows con un código 139xxx.
- Qué hacer
- Lee
meta_codeydetails[0].messagey corrige antes de reintentar.
catalog_not_found
- Estado HTTP
- 404
- Se puede repetir
- No
- Mensaje en el panel
- Catálogo no encontrado.
- Qué significa
- El catálogo no existe en esta organización.
- Qué hacer
- Revisa el
id(cat_…) y sincroniza los catálogos de la cuenta.
catalog_not_linked
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- El catálogo no está vinculado a esta cuenta de WhatsApp Business.
- Qué significa
- El catálogo no está vinculado a la cuenta de WhatsApp Business de la conexión.
- Qué hacer
- Vincula el catálogo (
POST /v1/catalogs/{id}/link) antes de usarlo en mensajes.
product_not_found
- Estado HTTP
- 404
- Se puede repetir
- No
- Mensaje en el panel
- Producto no encontrado.
- Qué significa
- El producto no existe en este catálogo.
- Qué hacer
- Revisa el
id(prd_…) o elretailer_idy sincroniza el catálogo.
commerce_permission_missing
- Estado HTTP
- 403
- Se puede repetir
- No
- Mensaje en el panel
- Falta el permiso catalog_management para este catálogo.
- Qué significa
- El token de la conexión no tiene el permiso
catalog_managementpara este catálogo. - Qué hacer
- Reconecta el número concediendo acceso al catálogo o usa un catálogo de la misma empresa.
order_not_found
- Estado HTTP
- 404
- Se puede repetir
- No
- Mensaje en el panel
- Pedido no encontrado.
- Qué significa
- El pedido no existe en esta organización.
- Qué hacer
- Revisa el
id(ord_…).
order_invalid_transition
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Este cambio de estado no está permitido en el estado actual del pedido.
- Qué significa
- El nuevo estado no sigue el flujo del pedido (p. ej.,
shippedantes del pago). - Qué hacer
- Lee el estado actual del pedido y avanza un paso a la vez.
order_reference_taken
- Estado HTTP
- 409
- Se puede repetir
- No
- Mensaje en el panel
- Este reference_id ya se usó en esta conexión.
- Qué significa
- Ya existe un pedido con este
reference_iden esta conexión. - Qué hacer
- Usa un
reference_idnuevo para cada pedido (hasta 35 caracteres).
order_totals_mismatch
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Los totales del pedido no cuadran.
- Qué significa
- El total no es subtotal + impuesto + envío − descuento, o el subtotal no es la suma de los ítems.
- Qué hacer
- Recalcula los valores en centavos (enteros) y vuelve a enviar.
payment_not_available
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- Forma de pago no disponible para este pedido.
- Qué significa
- La forma de pago no está disponible para este pedido (moneda, país o configuración de Meta).
- Qué hacer
- Usa BRL con Pix, link de pago o boleto; consulta la guía de comercio.
otp_template_invalid
- Estado HTTP
- 422
- Se puede repetir
- No
- Mensaje en el panel
- La plantilla de autenticación no existe o no está aprobada.
- Qué significa
- La plantilla de autenticación no existe o no está
APPROVED. - Qué hacer
- Créala con
POST /v1/templates/authenticationy espera la aprobación antes de enviar códigos.
body_too_large
- Estado HTTP
- 413
- Se puede repetir
- No
- Mensaje en el panel
- El cuerpo de la solicitud es demasiado grande para esta ruta.
- Qué significa
- El cuerpo de la solicitud supera el límite de esta ruta.
- Qué hacer
- Envía un cuerpo más pequeño; los medios grandes van por enlace o carga propia.
Errores de Meta en meta_code
Sección titulada «Errores de Meta en meta_code»Cuando Meta rechaza una llamada de la capa simple, Messajo devuelve su propio código en code, el código original de Meta en meta_code y el detalle de Meta en details[0].message. En la capa espejo (/v1/whatsapp/...) la respuesta de Meta vuelve tal cual, sin traducción: el espejo es la propia Meta.
meta_code |
code |
HTTP | Qué significa | Qué hacer |
|---|---|---|---|---|
| 131047 | outside_service_window |
422 | Pasaron más de 24 horas desde el último mensaje del contacto. Messajo lo comprueba antes de llamar a Meta y responde el mismo código. | Envía una plantilla aprobada para reabrir la conversación. |
| 131026 | recipient_unavailable |
422 | El mensaje no se pudo entregar (número sin WhatsApp, versión antigua, términos no aceptados). | No repitas; confirma el número con el contacto por otro canal. |
| 131049 | marketing_limit_reached |
422 | Meta retuvo la plantilla de marketing para cuidar la experiencia del usuario. | No repitas enseguida; prueba otro día u otro contenido. En una campaña, se pausa sola a partir del 10 %. |
| 131048 | meta_spam_rate_limited |
429 | Meta limitó el número por sospecha de spam (muchas denuncias o bloqueos). | No repitas; espera unas horas y baja el volumen. Una campaña se pausa sola. |
| 131056 | pair_rate_limited |
429 | Demasiados mensajes del mismo número al mismo contacto en poco tiempo. | Espera el retry_after_ms (6 s) y espacia los envíos; consulta Límite por par. |
| 130429 · 80007 · 4 | meta_rate_limited |
429 | El número o la app superó el rendimiento de Meta. | Repite después del Retry-After; consulta Envío por número. |
| 132000 | template_error |
422 | La cantidad de variables enviadas no coincide con la plantilla. | Envía exactamente los parámetros que define la plantilla. |
| 132001 | template_error |
422 | La plantilla no existe en el idioma pedido o todavía no fue aprobada. | Revisa el nombre, el idioma y el estado de la plantilla. |
| 132005 | template_error |
422 | El texto de la plantilla con las variables superó el tamaño máximo. | Acorta los valores de las variables. |
| 132007 | template_error |
422 | El contenido de las variables viola la política de Meta. | Revisa el texto enviado en las variables. |
| 132012 | template_error |
422 | El formato de un parámetro no coincide con la plantilla (p. ej., imagen en lugar de texto). | Envía cada parámetro con el tipo que define la plantilla. |
| 132015 | template_error |
422 | La plantilla se pausó por baja calidad. Messajo marca la plantilla como PAUSED. |
Edita la plantilla o usa otra hasta que la calidad se recupere. |
| 132016 | template_error |
422 | La plantilla se desactivó por baja calidad repetida. Messajo marca la plantilla como DISABLED. |
Crea una plantilla nueva. |
| 132068 · 132069 | template_error |
422 | El Flow de la plantilla está bloqueado o con el límite alcanzado. | Corrige el Flow en el Administrador de WhatsApp. |
| 368 · 131031 | policy_blocked |
403 | La cuenta se bloqueó por violar la política de Meta. La conexión pasa a Restringida. | Revisa el motivo en el Administrador de WhatsApp y corrígelo antes de enviar de nuevo. |
| 190 · 102 | connection_needs_reconnect |
409 | El token de acceso de la conexión es inválido o venció. | La conexión pasa a needs_reconnect y los dueños y admins reciben un correo con enlace de reconexión. Reconecta. |
| 131042 | meta_payment_required |
402 | Un problema con el método de pago de la cuenta en Meta. | Corrige el pago en el Administrador comercial. |
| 131030 | recipient_not_allowed |
422 | Número de prueba: el destinatario no está en la lista de permitidos. | Agrega el destinatario en el panel de la app de Meta. |
| 131051 · 131052 · 131053 | media_error |
422 | Tipo de mensaje no soportado, o Meta no pudo descargar o subir el archivo. | Revisa el formato y el tamaño; usa media_id en lugar de link. |
| 138006 | call_permission_required |
403 | El contacto no dio permiso para que la empresa llame. | Pide el permiso (ver Llamadas) y espera call.permission_updated. |
| 138xxx (límites de llamada) | call_rate_limited |
429 | Se superó el límite de llamadas o de solicitudes de permiso de Meta. | Espera; no repitas enseguida. |
| 138xxx (otros) | call_error |
422 | Meta rechazó la acción de la llamada. | Ver details[0].message. |
| 139001 | flow_invalid_json |
422 | Meta rechazó el JSON del Flow. | Corrige el punto citado en details (flow_json:<línea>:<columna>). |
| 139xxx (otros) | flow_error |
422 | Meta rechazó la operación en el Flow. | Ver details[0].message. |
| 200 · 10 en catálogo | commerce_permission_missing |
403 | A la app le falta el permiso catalog_management. |
Reconecta aceptando el permiso de catálogo. |
| 133005 | pin_invalid |
422 | El número ya tiene PIN de verificación en dos pasos y el PIN enviado no coincide. La conexión queda pending con motivo pin_required. |
Escribe el PIN de 6 dígitos en la página de la conexión (o en el enlace de conexión). Si no lo recuerdas, restablécelo en WhatsApp Manager. |
| 133016 · 133008 · 133009 | pin_attempts_exhausted |
429 | Límite de 10 registros por número en 72 h, o Meta pidió esperar. Messajo cuenta las llamadas y no envía la 11.ª. | Espera el retry_after_ms de la respuesta. |
| 133010 | number_not_registered |
409 | El número no está registrado en la Cloud API. | En la página de la conexión, usa Reintentar registro. |
| 147002 | username_not_eligible |
422 | La cuenta todavía no es elegible para un nombre de usuario en Meta. | Intenta de nuevo más tarde; la elegibilidad la decide Meta. |
| 100 | meta_invalid_parameter |
400 | Parámetro inválido en la llamada. | Corrige el campo indicado en details[0].message. |
| 131000 · 131016 · 133004 · 5xx | meta_unavailable |
503 | Meta está caída o sobrecargada, en una lectura. | Repite con backoff. |
| 131000 · 131016 · 133004 · 5xx | meta_unknown_outcome |
502 | El mismo fallo, pero en un envío: el mensaje puede haber salido. | No reenvíes a ciegas; consulta abajo. |
| otro | meta_error |
502 | Un código de Meta que Messajo no traduce. | Revisa meta_code y details[0].message. |
Instagram y Messenger
Sección titulada «Instagram y Messenger»Instagram y Messenger comparten la misma tabla, con el código y el subcódigo de Meta (meta_code / subcódigo). El espejo (/v1/instagram/..., /v1/messenger/...) devuelve la respuesta de Meta sin traducir.
meta_code |
code |
HTTP | Qué significa | Qué hacer |
|---|---|---|---|---|
| 10 / 2018278 · 10 / 2534022 | outside_service_window |
422 | Fuera de la ventana de 24 h (o de la de 7 días con la etiqueta). | Espera a que el contacto escriba; una respuesta de una persona puede usar tag: "human_agent". |
| 551 · 100 / 2018001 · 100 / 2534014 | recipient_unavailable |
422 | El contacto no está disponible (bloqueó la cuenta, borró el perfil o nunca conversó). | No repitas. |
10 / 2018065 · 200 con tag: human_agent |
human_agent_not_approved |
403 | Se usó la etiqueta HUMAN_AGENT sin la función Human Agent aprobada. |
Pide la función en App Review o responde dentro de 24 h. |
| 10 / 2534023 | private_reply_already_sent |
409 | El comentario ya recibió una respuesta privada. | Sigue la conversación por Direct. |
| 4 · 17 · 32 · 613 · 80006 | meta_rate_limited |
429 | La cuenta o la app superó el rendimiento de Meta. | Repite después del Retry-After. |
| 190 · 102 | connection_needs_reconnect |
409 | El token de la cuenta o de la Página no es válido. | La conexión pasa a needs_reconnect; reconecta. |
| 10 · 200 sin subcódigo mapeado (Messenger) | connection_needs_reconnect |
409 | La persona que conectó perdió su rol en la Página. La conexión pasa a needs_reconnect con motivo page_role_lost. |
Reconecta con alguien que administre la Página. |
| 200 / 2018028 · 10 · 3 | meta_permission_denied |
403 | Falta un permiso para esta acción. | Reconecta aceptando todos los permisos. |
| 100 / 2018047 | media_error |
422 | Adjunto rechazado (tipo, tamaño o URL). | Revisa el formato y el tamaño; usa media_id. |
| 368 · 10 / 2018320 | policy_blocked |
403 | Meta lo bloqueó por política. La conexión pasa a Restringida. | Revisa el motivo en Meta antes de enviar de nuevo. |
| 9 / 2207042 | publishing_limit_reached |
429 | La cuota de 100 publicaciones en 24 h está llena. | Messajo vuelve a intentar cada hora durante hasta 24 h. |
| 2207xxx | publication_media_invalid |
422 | Meta no aceptó o no pudo descargar el archivo de la publicación. | Revisa formato, tamaño y si la URL es pública. |
| 1 · 2 · 5xx | meta_unavailable |
503 | Meta está caída, en una lectura. | Repite con backoff. |
| 1 · 2 · 5xx | meta_unknown_outcome |
502 | La misma falla, en un envío: el mensaje puede haber salido. | No reenvíes a ciegas; mira abajo. |
| otro | meta_error |
502 | Código de Meta sin traducción en Messajo. | Mira meta_code y details[0].message. |
Envío sin respuesta segura
Sección titulada «Envío sin respuesta segura»Cuando Meta falla en medio de un envío (timeout, 5xx), no hay forma de saber si el mensaje salió. Messajo no reintenta: guarda el mensaje con el error meta_unknown_outcome y responde 502 con retryable: false. Confirma con el contacto o en el celular antes de enviar de nuevo. Repetir con la misma Idempotency-Key devuelve la misma respuesta, sin reenviar; para enviar de nuevo a propósito, usa una clave nueva.
Hablar con soporte
Sección titulada «Hablar con soporte»Envía el request_id del error (o el encabezado X-Request-Id), la hora aproximada y el code. Con el request_id soporte encuentra la solicitud exacta en los logs.