> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rail.cl/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Reintenta POSTs sin riesgo de doble efecto.

## Por qué

Si tu request falla con timeout o 5xx, no sabes si Rail lo recibió o no. Si reintentas, ¿corres el riesgo de crear el recurso 2 veces? Con `Idempotency-Key` no.

## Uso

Envía el header `Idempotency-Key` con un UUID que generaste tú:

```bash theme={null}
curl https://api.rail.cl/v1/refresh_intents \
  -X POST \
  -H "Authorization: Bearer rail_sk_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"link_id": "link_xxx", "refresh_type": "full"}'
```

Rail:

* En el primer request: procesa normal y **guarda el response** asociado a tu key.
* En requests subsecuentes con la **misma key**: devuelve el response cacheado, **sin re-procesar**.

## TTL

24 horas. Después de eso, la key se libera y un nuevo request con esa key se procesa como nuevo.

## Reglas

* Solo aplica a **POST** y **DELETE**. GETs son idempotentes por naturaleza.
* La key debe ser única por intención lógica de tu cliente — genérala con `uuid.v4()` o equivalente.
* Si reúsas la misma key con un body **diferente**, devuelve `409 Conflict` con `error.code: idempotency_conflict`.

## Endpoints que lo aceptan

| Endpoint                        | Recomendado                                                                    |
| ------------------------------- | ------------------------------------------------------------------------------ |
| `POST /v1/widget_tokens`        | <Icon icon="circle-check" color="#16a34a" />                                   |
| `POST /v1/refresh_intents`      | <Icon icon="circle-check" color="#16a34a" />                                   |
| `POST /v1/exchange_tokens/{id}` | <Icon icon="triangle-exclamation" color="#f59e0b" /> (one-shot por naturaleza) |
| `POST /v1/webhook_endpoints`    | <Icon icon="circle-check" color="#16a34a" />                                   |
| `DELETE /v1/links/{id}`         | <Icon icon="circle-check" color="#16a34a" />                                   |