Ir al contenido

API y SDK

Errores

El formato único de error de la API y el significado de cada código.

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 Unauthorized
Content-Type: application/json
X-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").
  • Repite solo cuando retryable sea true. Los demás piden una corrección antes.
  • Si la respuesta trae Retry-After (segundos) o retry_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-Key y repite con la misma clave, para no entregar el mensaje dos veces. Mira Límites.

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 el path del 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 /v1 con 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 el Retry-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.

service_unavailable

Estado HTTP
503
Se puede repetir
Sí
Mensaje en el panel
Servicio no disponible temporalmente. Inténtalo de nuevo en unos instantes.
Qué significa
El servicio o una de sus dependencias está caído por un momento.
Qué hacer
Repite con backoff exponencial respetando el Retry-After, cuando exista.

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_SECRET sea 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-Key ya 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-Key todaví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, http sin permiso, host inválido).
Qué hacer
Lee details[].message con el motivo y usa una URL https pú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.

recipient_unavailable

Estado HTTP
422
Se puede repetir
No
Mensaje en el panel
No se pudo entregar a este destinatario.
Qué significa
Meta no pudo entregar: el número no tiene WhatsApp, su app está desactualizada o no aceptó los términos nuevos.
Qué hacer
Revisa el número con el código de país. No repitas enseguida: el resultado será el mismo hasta que el destinatario lo resuelva.

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 cabecera Retry-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[].message y meta_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[].message y meta_code, corrige el campo y envía de nuevo.

meta_unavailable

Estado HTTP
503
Se puede repetir
Sí
Mensaje en el panel
Meta no está disponible por el momento. Inténtalo de nuevo en breve.
Qué significa
Meta respondió con un fallo temporal en una lectura u otra llamada que se puede repetir sin efecto duplicado.
Qué hacer
Repite con backoff. Si dura, mira la página de estado de Meta.

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 queued hasta que el estado llegue por webhook.
Qué hacer
No reenvíes a ciegas. Confirma con el evento message.status o con el contacto; repetir con la misma Idempotency-Key devuelve 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_code y details[].message y busca el código en la documentación de Meta. Guarda el request_id si 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_disabled y connection_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_ms antes 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_ms y 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 code que 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.

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].message trae 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 state que 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 MESSAGING o MANAGE), 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, como template en Instagram o cards en 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 (como human_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_agent solo 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. details dice 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 status de 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 el status de 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_ms o 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 de HMAC-SHA256.
Qué hacer
Revisa que la URL del callback en la app de Meta apunte a este servidor y que META_APP_SECRET sea 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 cursor enviado no lo generó esta ruta con estos mismos filtros, o fue modificado.
Qué hacer
Envía el next_cursor tal como vino en la respuesta anterior, con los mismos filtros. Para empezar de nuevo, omite el cursor.

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á APPROVED en Meta o su categoría no se usa en campañas (solo MARKETING y UTILITY).
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 el path del 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 en scheduled, paused y auto_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 status actual de la campaña.
Qué hacer
Consulta la campaña, revisa el status y 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 quedaron invalid.
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 completed o failed y 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_at está 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/ws con 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/ws no 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 details o en GET /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 que accept use exactamente el mismo SDP.
Qué hacer
Guarda el SDP del pre_accept y reenvía el mismo texto en accept.

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 evento call.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_code y details[0].message para 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.created antes 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 details trae path = 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 necesita FLOWS_ENDPOINT_BASE_URL con https:.

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/rotate y 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_code y details[0].message y 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 el retailer_id y 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_management para 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., shipped antes 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_id en esta conexión.
Qué hacer
Usa un reference_id nuevo 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/authentication y 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.

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 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.

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.

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.