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

# Idempotencia

> Cómo reintentar un pedido que modifica algo sin que el efecto se repita.

> [!NOTE]
>
> Hoy todas las rutas de la API son de lectura (`GET`). Una lectura se puede repetir cuantas veces
> quieras sin efecto, así que hoy no necesitas nada de esta página. Esta regla aplica a todo pedido que no
> sea `GET`.

Un pedido que crea o modifica algo puede fallar a mitad de camino: se corta la conexión, vence un
timeout y no sabes si llegó. Para que reintentar sea seguro, todo pedido que no es `GET` lleva el header
`Idempotency-Key`:

```bash theme={null}
-H "Idempotency-Key: 5f0c6a1e-8a3b-4d2f-9c1e-2b7d4e6f8a90"
```

* Usa un valor único por operación, por ejemplo un UUID nuevo. Hasta 255 caracteres.
* Si repites el pedido con **la misma clave y el mismo cuerpo**, recibes la respuesta guardada del
  primero, con el header `Idempotent-Replayed: true`, y el efecto no se repite.
* Si usas la misma clave con un pedido distinto, la respuesta es
  [`idempotency_key_reused`](https://docs.craqui.com/errors/idempotency_key_reused).
* Si repites mientras el primero todavía se procesa, la respuesta es
  [`idempotency_in_progress`](https://docs.craqui.com/errors/idempotency_in_progress): espera y repite.
* Sin el header, la respuesta es [`idempotency_key_required`](https://docs.craqui.com/errors/idempotency_key_required).

Una clave de idempotencia vale para la clave de la API que la usó y por 24 horas. Una respuesta `5xx` no
se guarda: puedes reintentar con la misma `Idempotency-Key`.

Con una clave de prueba, la idempotencia también está atada al estudio de prueba que respondió: después
de restablecerlo, repetir una `Idempotency-Key` de antes responde `idempotency_key_reused` en vez de la
respuesta guardada.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.