# Idempotencia

Las redes fallan. Cuando a un `POST` se le agota el tiempo, no puedes saber si llegó a la API. Con una `Idempotency-Key` puedes enviarlo de nuevo sin verificar, crear ni cobrar dos veces.

## Cómo funciona

Añade la cabecera a cualquier `POST`: `/verify`, `/batches` y `/batches/{batch_id}/cancel`.

```bash
curl https://api.salchimail.com/v1/verify \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c1c0e-6d1f-4f0e-9f58-0d6b0a1c2e3f" \
  -d '{"email": "ana@example.com", "mode": "mailbox"}'
```

- La clave es cualquier cadena única de hasta 255 caracteres. Un UUID es una buena opción.
- Las claves se guardan **24 horas**, por cuenta.
- Un reintento con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con la cabecera `Idempotent-Replayed: true`, y **no cobra nada**.

## Conflictos

| HTTP | `code` | Significado | Qué hacer |
| --- | --- | --- | --- |
| 409 | `idempotency_key_reused` | La clave ya se usó con un cuerpo distinto | Usa una clave nueva para una petición nueva |
| 409 | `idempotency_in_progress` | La primera petición con esa clave sigue en curso | Espera y reintenta con la misma clave |

```json
{
  "error": {
    "type": "conflict",
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request.",
    "request_id": "req_4b5c6d7e8f9a0b22"
  }
}
```

## Úsala bien

- Genera **una clave por operación**, no por intento: créala antes del primer intento y reutilízala en cada reintento.
- Guarda la clave junto al trabajo al que pertenece (el registro, la importación) para que un proceso reiniciado reintente con la misma clave.
- Reintenta ante errores de red, `429`, `500` y `503`, con la misma clave y una espera creciente. Consulta [Límites y errores](https://docs.salchimail.com/es/limites-y-errores.md).
- No reintentes `400`, `401`, `402`, `403` ni `404` sin cambiar algo: la respuesta será la misma.

La idempotencia importa sobre todo al [crear un lote](https://docs.salchimail.com/es/lotes.md): sin clave, un reintento tras un tiempo de espera agotado puede crear un segundo lote y reservar también sus créditos.

Las peticiones `GET` se pueden repetir sin riesgo y no necesitan clave.
