Idempotencia

Un fallo de red puede dejarle sin saber si una solicitud llegó. Sin protección, el reintento aparentemente seguro podría verificar dos veces la misma dirección. Una clave de idempotencia hace inofensivo el reintento: la API la reconoce y responde con el resultado que ya registró.

El encabezado

Envíe Idempotency-Key: <valor> en cualquier solicitud que cree algo:

• POST /v1/checks y POST /v1/checks/batch
• POST /v1/webhooks, POST /v1/webhooks/{webhook_id}/rotate y DELETE /v1/webhooks/{webhook_id}
• POST /v1/telegram/link-codes y DELETE /v1/telegram/links/{link_id}

El encabezado es opcional. El valor tiene de 1 a 255 caracteres ASCII imprimibles sin espacios; cualquier otro se rechaza con 400 VALIDATION_ERROR y parameter: "idempotency-key". Use su propio identificador de operación (un número de pedido, un identificador de pago), no un valor aleatorio por intento: lo esencial es que todos los intentos de una misma operación envíen la misma clave.

Una clave se limita a su cuenta, al entorno de la clave (live o sandbox) y al endpoint, de modo que el mismo valor en dos endpoints, o con una clave sandbox y una live, no colisiona. Las claves se recuerdan durante 24 horas; después el valor puede reutilizarse.

Qué ocurre cuando se reutiliza una clave

Usted envía	La API responde
La clave por primera vez	Ejecuta la solicitud y registra su resultado bajo la clave.
La misma clave y el mismo cuerpo, una vez terminada la primera solicitud	Reproduce el resultado registrado: el mismo código de estado y el mismo recurso (en una verificación, el mismo check_id). No se verifica ni se cobra nada otra vez.
La misma clave y un cuerpo distinto	422 IDEMPOTENCY_KEY_CONFLICT. No se ejecuta nada.
La misma clave mientras la primera solicitud sigue en curso	409 IDEMPOTENCY_REQUEST_IN_FLIGHT. Espere un momento y envíela de nuevo.
La misma clave después de que un reintento simultáneo tomara el arrendamiento de la primera solicitud	409 IDEMPOTENCY_LEASE_LOST para la solicitud que lo perdió. Envíe de nuevo la misma solicitud para leer el resultado registrado.

Detalles que importan en la práctica:

• «El mismo cuerpo» significa los mismos bytes. El cuerpo se compara tal como se envía, no tras analizarlo, así que un reintento que reserialice el JSON con otro orden de claves o espaciado cuenta como un cuerpo distinto. Guarde la solicitud serializada y reenvíela sin cambios.
• Solo se registran los resultados correctos. Una solicitud que termina en 4xx o 5xx no queda asociada a su clave, así que un reintento se ejecuta de nuevo, que es lo que se quiere tras un fallo transitorio. Si el error fue un 4xx, corrija antes la solicitud.
• Una solicitud caída no bloquea la clave. Si el primer intento muere sin responder, un reintento toma la clave tras 30 segundos.
• El secreto de un webhook se muestra una sola vez. Reproducir POST /v1/webhooks o una rotación devuelve el webhook sin su secret, porque el secreto nunca se guarda en forma legible. Si perdió la respuesta, rote con una clave nueva.
• Los elementos de un lote reciben claves derivadas. La clave de cada elemento de un lote se forma con la clave del lote y su posición, de modo que reproducir un lote no puede verificar un elemento dos veces.

Ejemplo

Envíe la misma solicitud, con la misma clave y el mismo cuerpo, hasta obtener una respuesta. El cuerpo es la dirección de prueba de sandbox, que siempre responde pending, así que ejecútelo con una clave sandbox.

curl

curl -s -X POST https://api.leeri.ai/v1/checks \
  -H "Authorization: Bearer $LEERI_API_KEY" \
  -H "Idempotency-Key: deposit-2291-attempt-group" \
  -H "Content-Type: application/json" \
  -d '{"subject":"address","asset":"BTC","address":"1PENDNGCHECKADDRESSFRSANDBXTEST99"}'

Ejecútelo dos veces: la segunda respuesta lleva el mismo check_id que la primera.

Node.js

const body = JSON.stringify({ subject: 'address', asset: 'BTC', address: '1PENDNGCHECKADDRESSFRSANDBXTEST99' });

async function screen(operationId) {
  for (let attempt = 1; attempt <= 5; attempt += 1) {
    try {
      const response = await fetch('https://api.leeri.ai/v1/checks', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${process.env.LEERI_API_KEY}`,
          'Idempotency-Key': operationId,
          'Content-Type': 'application/json',
        },
        body,
      });
      const retryable = response.status === 409 || response.status >= 500;
      if (!retryable) return await response.json();
    } catch {
      // fallo de red: la solicitud pudo llegar o no, así que se reintenta con la misma clave
    }
    await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 250));
  }
  throw new Error('check not confirmed after 5 attempts');
}

console.log(await screen('deposit-2291'));

Python

import json
import os
import time

import requests

body = json.dumps({"subject": "address", "asset": "BTC", "address": "1PENDNGCHECKADDRESSFRSANDBXTEST99"})


def screen(operation_id):
    for attempt in range(1, 6):
        try:
            response = requests.post(
                "https://api.leeri.ai/v1/checks",
                headers={
                    "Authorization": f"Bearer {os.environ['LEERI_API_KEY']}",
                    "Idempotency-Key": operation_id,
                    "Content-Type": "application/json",
                },
                data=body,
                timeout=30,
            )
            if response.status_code != 409 and response.status_code < 500:
                return response.json()
        except requests.RequestException:
            pass  # la solicitud pudo llegar o no, así que se reintenta con la misma clave
        time.sleep(2**attempt * 0.25)
    raise RuntimeError("check not confirmed after 5 attempts")


print(screen("deposit-2291"))

Para reaccionar ante otros fallos, vea Errores.