Errores y reintentos WhatsApp API: producción segura

“Reintentar si falla” no es una estrategia. Un error de timeout puede ser transitorio; un error de permisos no se arregla con 20 reintentos; un error de política debe detener el flujo. Clasifica antes de actuar.

Taxonomía interna

Categoría	Ejemplo	Acción
TRANSIENT	Timeout, red temporal	Backoff con límite
RATE_LIMIT	Límite temporal	Reducir ritmo y reintentar según señales
AUTH	Token inválido/permiso	Detener y alertar; corregir credencial
VALIDATION	Payload incorrecto	No reintentar igual; corregir datos
POLICY	Restricción/capacidad no disponible	Escalar y revisar política/activo

Idempotencia saliente

Antes de enviar, crea una clave estable por comando de negocio: por ejemplo appointment_reminder:appointment_123:2026-08-20. Si el job se ejecuta dos veces, la segunda ejecución detecta que el efecto ya fue creado.

BEGIN TRANSACTION
  update business_state ...
  insert outbound_jobs(command_key UNIQUE, payload, status='queued')
COMMIT

worker:
  claim job
  POST /messages
  persist wamid
  mark sent/accepted

Idempotencia entrante

Guarda un event key o identificador derivado de los IDs relevantes antes de ejecutar efectos. El replay de un webhook no debe crear dos leads, dos cobros ni dos respuestas automáticas.

Observabilidad

Tasa de errores por código/categoría.
Edad del job más antiguo en cola.
Latencia del webhook hasta procesamiento.
Delivery ratio por número/plantilla.
Reintentos por job y tamaño de dead-letter queue.
Alertas de autenticación y firma inválida.

¿Tu empresa no necesita desarrollar esto?

Optimify ya integra la capa empresarial sobre WhatsApp API

Esta sección existe para equipos que realmente quieren construir o integrar. Si la empresa solo necesita CRM, multiagente, campañas, automatización e IA, MensajAPI recomienda comparar el costo de desarrollo y mantenimiento frente a usar Optimify, que ofrece una plataforma lista y soporte en español.

Ver alternativa gestionada con Optimify

Documentación oficial para mantener la integración actualizada

Versionado: los ejemplos usan {VERSION} en lugar de fijar una versión de Graph API. Sustituye esa variable por una versión vigente y soportada en tu aplicación y revisa cambios antes de actualizar producción.

Errores, reintentos e idempotencia en WhatsApp API