# Clave de idempotencia (Idempotency-Key)

> Un valor único que hace que un reintento devuelva el primer resultado y no un duplicado. Cómo la API de CryptoLike usa Idempotency-Key, order_id y payout_id.

Source: https://cryptolike.net/es/glossary/idempotency-key
Updated: 2026-09-25

Un valor único que un cliente adjunta a una solicitud para que, si la repite tras un tiempo de espera agotado o un error, reciba el primer resultado en lugar de crear un duplicado.

## Cómo funciona en CryptoLike

La API de CryptoLike acepta un encabezado `Idempotency-Key` en cada `POST`: hasta 128 caracteres ASCII imprimibles (de `!` a `~`), por ejemplo el ID de tu pedido. Un encabezado vacío o solo con espacios cuenta como ausente; una clave más larga o con otros caracteres recibe `400 validation_error` para el campo `Idempotency-Key`. Una solicitud repetida con la misma clave devuelve la respuesta original con `Idempotent-Replayed: true`, y nada se crea dos veces. Las claves se recuerdan durante 24 horas por cada clave API, así que un reintento dentro de ese plazo nunca crea un segundo pago ni un segundo retiro.

La repetición debe ser la misma solicitud: mismo método, ruta y cuerpo. Un cuerpo distinto con la misma clave da `422 idempotency.mismatch`: usa una clave por cada operación lógica. Si la primera solicitud sigue en curso, la respuesta es `409 idempotency.in_progress`: espera y repite. Solo se guardan las respuestas por debajo de 400; un error libera la clave, así que un reintento corregido se ejecuta de nuevo. Después de `504 timeout`, reintenta con la misma clave. Los SDK oficiales agregan el encabezado a cada `POST` por ti.

Hay dos protecciones más que funcionan sin el encabezado. En `POST /v1/invoices`, `idempotency_by_order_id: true` devuelve el pago abierto del mismo `order_id` en lugar de crear otro. En `POST /v1/withdrawals`, tu `payout_id` con la misma moneda, el mismo monto y la misma dirección devuelve el retiro existente, mientras que con parámetros distintos la respuesta es `409`: un reintento con el mismo `payout_id` no paga dos veces. Del lado receptor, el código que procesa los [webhooks](https://cryptolike.net/es/glossary/webhook) deduplica por `event_id`.

## Ejemplo

Una solicitud de pago de CryptoLike con clave de idempotencia: si la conexión se corta antes de que llegue la respuesta, envía otra vez la misma solicitud —misma clave y mismo cuerpo, firmada de nuevo con una marca de tiempo nueva, al menos un segundo después— y recibes el mismo pago. `$KEY_ID`, `$TS` y `$SIG` son los valores de firma de la [guía de autenticación de la API](https://cryptolike.net/docs/auth):

```bash
curl -s https://api.cryptolike.net/v1/invoices \
  -H "Content-Type: application/json" -H "Idempotency-Key: order-A-1001" \
  -H "X-API-Key: $KEY_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -d '{"amount":"10.50","currency":"USD","order_id":"A-1001"}'
```