# Errores

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

## 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
HTTP/1.1 401 Unauthorized
Content-Type: application/json
X-Request-Id: req_01a1c036cb127000b175ffba86a20018
```

```json
{
  "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"
  }
}
```

## Campos

| 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

- 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](/es/api/limits#idempotency-key).

## 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
- 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
- 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](/api/authentication).

### invalid_api_key
- Estado HTTP: 401
- Se puede repetir: no
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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](/api/authentication#tipos-de-clave).

### two_factor_required
- Estado HTTP: 403
- Se puede repetir: no
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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: yes
- 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](/api/limits).

### internal_error
- Estado HTTP: 500
- Se puede repetir: yes
- 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: yes
- 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
- 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
- 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
- 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
- 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: yes
- 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
- 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: yes
- 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
- 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
- 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
- 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
- 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
- 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
- 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: yes
- 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: yes
- 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](/api/limits).

### template_error
- Estado HTTP: 422
- Se puede repetir: no
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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: yes
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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: yes
- 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
- 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
- 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: yes
- 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](/api/limits).

### account_flagged
- Estado HTTP: 403
- Se puede repetir: no
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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: yes
- Qué significa: Demasiadas contraseñas incorrectas seguidas bloquearon el enlace por un tiempo.
- Qué hacer: Espera `retry_after_ms` e inténtalo de nuevo con la contraseña correcta.

### link_password_required
- Estado HTTP: 401
- Se puede repetir: no
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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: yes
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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: yes
- 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
- 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
- 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
- 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: yes
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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

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`](/es/errors#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`](/es/errors#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`](/es/errors#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](/es/guides/campaigns/#131049-y-las-24-horas), se pausa sola a partir del 10 %. |
| 131048 | [`meta_spam_rate_limited`](/es/errors#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`](/es/errors#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](/es/api/limits#límite-por-par). |
| 130429 · 80007 · 4 | [`meta_rate_limited`](/es/errors#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](/es/api/limits#envío-por-número). |
| 132000 | [`template_error`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#template_error) | 422 | El contenido de las variables viola la política de Meta. | Revisa el texto enviado en las variables. |
| 132012 | [`template_error`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#call_permission_required) | 403 | El contacto no dio permiso para que la empresa llame. | Pide el permiso (ver [Llamadas](/es/guides/calls/)) y espera `call.permission_updated`. |
| 138xxx (límites de llamada) | [`call_rate_limited`](/es/errors#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`](/es/errors#call_error) | 422 | Meta rechazó la acción de la llamada. | Ver `details[0].message`. |
| 139001 | [`flow_invalid_json`](/es/errors#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`](/es/errors#flow_error) | 422 | Meta rechazó la operación en el Flow. | Ver `details[0].message`. |
| 200 · 10 en catálogo | [`commerce_permission_missing`](/es/errors#commerce_permission_missing) | 403 | A la app le falta el permiso `catalog_management`. | Reconecta aceptando el permiso de catálogo. |
| 133005 | [`pin_invalid`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#meta_unavailable) | 503 | Meta está caída o sobrecargada, en una lectura. | Repite con backoff. |
| 131000 · 131016 · 133004 · 5xx | [`meta_unknown_outcome`](/es/errors#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`](/es/errors#meta_error) | 502 | Un código de Meta que Messajo no traduce. | Revisa `meta_code` y `details[0].message`. |

### 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`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#meta_permission_denied) | 403 | Falta un permiso para esta acción. | Reconecta aceptando todos los permisos. |
| 100 / 2018047 | [`media_error`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#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`](/es/errors#meta_unavailable) | 503 | Meta está caída, en una lectura. | Repite con backoff. |
| 1 · 2 · 5xx | [`meta_unknown_outcome`](/es/errors#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`](/es/errors#meta_error) | 502 | Código de Meta sin traducción en Messajo. | Mira `meta_code` y `details[0].message`. |

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

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.
