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 entre todas sus claves, definido por su plan: 20 solicitudes por segundo en Scale, 10 por segundo en Growth y 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.
Solicitudes en curso al mismo tiempo
La API también limita cuántas solicitudes puede tener en curso una misma clave a la vez. Por encima de ese límite, o cuando la API en conjunto está al máximo de capacidad, una solicitud devuelve503 con "server_busy" y Retry-After: 1. La solicitud no se ejecutó y no cuenta contra tu presupuesto, así que reinténtala después de la espera.
Las llamadas que esperan la respuesta de la anterior no lo verán; una ráfaga de muchas llamadas en paralelo sí puede. Para enviar una plantilla a muchas personas, incluye hasta 100 destinatarios en cada POST /v1/templates/{id}/send en vez de hacer una llamada por destinatario.
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. Úsalo tras un timeout, cuando 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, así que 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 cambia seguido. 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 e ignora lo que no reconozcas.
- Cada cambio del contrato aparece en el changelog. Revísalo cuando algo se vea distinto.