Skip to main content

​
¿Qué es?

La idempotencia garantiza que una request repetida no genere efectos duplicados. Si tu sistema reintenta un envío (por timeout, error de red, etc.), el mismo mensaje no se envía dos veces.

​
Endpoints que soportan idempotencia

EndpointIdempotencia
POST /messagesSoportada (header Idempotency-Key)
Otros endpointsNo aplica

​
Cómo usarla

Incluí el header Idempotency-Key con un valor único por operación: 
curl -X POST https://api.waspytech.com/api/v2/messages \
  -H "Authorization: Bearer wspy_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: orden-1847-confirmacion" \
  -d '{
    "phoneNumberId": "uuid-del-canal",
    "to": "+5491126032641",
    "type": "text",
    "text": "Tu pedido #1847 fue confirmado."
  }'

​
Comportamiento

SituaciónResultado
Primera request con la keySe procesa normalmente, respuesta 201
Request repetida con la misma keyDevuelve la respuesta original cacheada con header Idempotency-Replayed: true
Request concurrente con la misma keyDevuelve 409 IDEMPOTENCY_CONFLICT

​
Respuesta repetida (replay)

HTTP/1.1 201 Created
Idempotency-Replayed: true

{
  "data": { "id": "msg-uuid", "status": "queued" },
  "meta": { "requestId": "nuevo-request-id" }
}

​
Conflicto concurrente

{
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "Otra request con esta Idempotency-Key está en proceso.",
    "status": 409
  },
  "meta": { "requestId": "..." }
}

​
Detalles técnicos

  • TTL: 24 horas. Después de 24hs, la misma key se puede reutilizar.
  • Largo máximo: 256 caracteres.
  • Scope: La key es única por cuenta (tenant). Dos cuentas pueden usar la misma key sin conflicto.

​
Buenas prácticas

  • Usá un identificador de tu sistema como key (ej: orden-1847-confirmacion, pago-uuid-notify).
  • No uses valores aleatorios (eso anula el propósito).
  • Si recibís un timeout, reintentá con la misma key — la respuesta original se va a devolver.