Idempotencia

Las redes fallan: una petición puede agotar el tiempo de espera sin que sepas si el mensaje salió. Con Idempotency-Key puedes reintentar sin generar un nuevo envío lógico.

POST /api/v1/messages acepta el header Idempotency-Key: de 1 a 255 caracteres ASCII imprimibles, sin espacios. Usa una clave por cada mensaje lógico; por ejemplo, el id de tu pedido.

curl -X POST "https://zappio.cloud/api/v1/messages" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1042" \
  -d '{"instance": "ins_...", "to": "5215500000000", "type": "text", "text": "Tu pedido 1042 va en camino"}'

Qué pasa en cada caso

Situación	Respuesta
Primera petición con esa clave.	202 Accepted: el mensaje queda en cola.
Misma clave y la misma petición, dentro de 24 horas.	200 OK con el mensaje original y el header Idempotent-Replayed: true. No se envía nada nuevo y no cuenta contra tu plan.
Misma clave con una petición distinta.	422 IDEMPOTENCY_KEY_REUSED.
Clave con formato inválido.	422 INVALID_IDEMPOTENCY_KEY.

Las claves se recuerdan durante 24 horas y pertenecen a la API key que las usó.

Cómo usarla bien

• Genera la clave a partir de algo estable de tu lado (el id del pedido), no al azar en cada intento.
• Si la petición falla por tiempo de espera o por un error de red, reintenta con la misma clave.
• Si recibes 200 con Idempotent-Replayed: true, el mensaje ya existe: no hagas nada más.
• Usa una clave distinta para cada mensaje distinto, aunque el contenido sea parecido.