Errores
Los errores usan códigos de estado convencionales con undetail legible por máquina:
Los errores estructurados siempre llevan un
code estable sobre el que puedes ramificar; las claves adicionales (como conflicting_contact_id en un contacto duplicado) te dan lo necesario para resolverlo. Cada forma de error está publicada en la referencia de la API.
Enviar una plantilla
POST /v1/templates/{id}/send rechaza la solicitud completa en vez de encolar una parte, así que un rechazo nunca te deja a medio enviar ni te cuesta nada. Los códigos sobre los que conviene ramificar:
GET /v1/templates/{id}/send-requirements te dice qué necesita una plantilla antes de enviar, así que la mayoría de estos nunca tienen que ocurrir.
Límites de uso
Cada organización tiene un presupuesto compartido de 20 solicitudes por segundo entre todas sus claves — 5 por segundo durante la prueba gratuita. Por encima del presupuesto, las solicitudes devuelven429 con un encabezado Retry-After (segundos; siempre 1, porque la ventana es de un segundo).
Cada respuesta — incluido el 429 — lleva tu presupuesto actual, para que puedas dosificar sin contar llamadas tú mismo:
Lee
X-RateLimit-Remaining y baja el ritmo conforme se acerca a cero, en vez de correr hasta el 429. Si tu integración realmente necesita más, habla con nosotros.
Una solicitud es una solicitud, sin importar cuánto haga.
POST /v1/templates/{id}/send cuenta una sola vez lleve un destinatario o cien — así que agrupar destinatarios en un solo envío es la forma más barata de mantenerte dentro del presupuesto. Lo que acota el volumen real de mensajes es el propio límite móvil de 24 horas de WhatsApp, no este.Reintentar de forma segura
POST /v1/templates/{id}/send acepta un encabezado Idempotency-Key. Envía la misma clave otra vez dentro de 24 horas y recibes la campaña original en lugar de un segundo envío — que es lo que quieres tras un timeout, cuando realmente no puedes saber si la solicitud llegó. Usa una clave nueva para cada envío distinto.
Paginación
Los endpoints de listado devuelven:next_cursor de vuelta como ?cursor= para traer la siguiente página; un cursor null significa que llegaste al final. Los cursores son opacos — no los parsees.
Las listas de propiedades y etapas del funnel no se paginan: devuelven el conjunto completo, sin next_cursor.
Compatibilidad
Esta es una API joven y en rápido movimiento — espera que evolucione. Dos hábitos mantienen tu integración estable:- La mayoría de los cambios son aditivos: nuevos endpoints, nuevos parámetros opcionales, nuevos campos de respuesta, nuevos valores en campos de texto. Tolera campos y valores desconocidos — ignora lo que no reconozcas.
- Cada cambio del contrato aparece en el changelog — revísalo cuando algo se vea distinto.