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

# Idempotencia

> Cómo evitar envíos duplicados usando Idempotency-Key.

## ¿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

| Endpoint         | Idempotencia                         |
| ---------------- | ------------------------------------ |
| `POST /messages` | Soportada (header `Idempotency-Key`) |
| Otros endpoints  | No aplica                            |

***

## Cómo usarla

Incluí el header `Idempotency-Key` con un valor único por operación:

```bash theme={null}
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ón                                                     | Resultado                                                                                                                                                                                                        |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Primera request con la key                                    | Se 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 transitorio          | **Si 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 theme={null}
HTTP/1.1 201 Created
Idempotency-Replayed: true
```

```json theme={null}
{
  "data": { "id": "msg-uuid", "status": "queued" },
  "meta": { "requestId": "nuevo-request-id" }
}
```

### Conflicto concurrente

```json theme={null}
{
  "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.