Clave de idempotencia (Idempotency-Key)

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

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"}'