Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.waspytech.com/llms.txt

Use this file to discover all available pages before exploring further.

​
¿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": { "body": "Tu pedido #1847 fue confirmado." }
  }'

​
Comportamiento

SituaciónResultado
Primera request con la keySe procesa normalmente, respuesta 201
Request repetida con la misma key (después de la 1ra exitosa)Devuelve la respuesta original cacheada con header Idempotency-Replayed: true
Request concurrente con la misma key (1ra todavía procesando)Devuelve 409 IDEMPOTENCY_CONFLICT
Request repetida después de un 503/error transitorioSi la 1ra alcanzó a insertar el mensaje, recibís la response cacheada con el mismo data.id. Si nunca llegó a insertarse, se procesa como nueva. Esto es exactamente lo que querés para hacer retry seguro.
Request repetida después de 5xx que NO completóEl lock expira a los 30s. Pasados esos 30s el retry se procesa como nueva request.

​
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.
  • Comparación: string equality, no hash. No hay riesgo de “colisión de hash” — Idempotency-Key: A y Idempotency-Key: B siempre se tratan como distintas. Cualquier string ≤256 chars es válido.
  • Política ante mismo body con misma key: se devuelve la respuesta original cacheada (replay).
  • Política ante body distinto con misma key: Waspy NO valida que el body sea idéntico. Devuelve la respuesta original. Es responsabilidad del integrador no reutilizar la misma key para envíos diferentes — usar identificadores únicos del lado tuyo (ej. orden-1847-confirmacion).

​
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.