Idempotency

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ú:

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`
`POST /v1/refresh_intents`
`POST /v1/exchange_tokens/{id}`	(one-shot por naturaleza)
`POST /v1/webhook_endpoints`
`DELETE /v1/links/{id}`

Empezar

Conceptos

Guías

Idempotency

Por qué

Uso

TTL

Reglas

Endpoints que lo aceptan

​Por qué

​Uso

​TTL

​Reglas

​Endpoints que lo aceptan

Por qué

Uso

TTL

Reglas

Endpoints que lo aceptan