Pending y sondeo

La mayoría de las verificaciones responden en la misma respuesta. Cuando una no puede, la API no le hace esperar con una conexión abierta: acepta la verificación y responde status: "pending" con un check_id. El cuerpo tiene exactamente la misma forma que una verificación completada, de modo que el código que lee la respuesta no cambia; solo ramifica según data.status.

Por qué una verificación queda pending

Una verificación pasa a una cola, y responde pending, cuando necesita realmente más tiempo del que debería retener una solicitud:

• una fuente de datos de terceros está ocupada y las consultas deben esperar su turno,
• un recorrido en frío de la cadena tarda más que el presupuesto de la solicitud, o
• la verificación llegó al final del tiempo que se le dio para responder dentro de la solicitud.

Mientras una verificación espera la evidencia requerida no hay veredicto, ni cobro, ni webhook de finalización. Todo se liquida una sola vez, cuando la verificación termina.

Los campos de espera

Campo	Mientras está pending	Una vez terminal
status	pending	completed o failed
pending_reason	Por qué la verificación espera evidencia, por ejemplo provider_pending (hay consultas en curso en una fuente de datos de terceros) o provider_capacity (espera de capacidad para consultas). Informativo: no ramifique según valores que no conozca. null cuando la verificación simplemente está en cola.	null
deadline_at	La hora configurada para la que la verificación habrá terminado. Es un límite, no una estimación: la mayoría de las verificaciones terminan mucho antes. Para las verificaciones nativas y de lote, por defecto son 24 horas tras la aceptación.	Se conserva tal como se registró. null para una verificación que nunca tuvo que esperar.
next_attempt_at	La hora más temprana a la que está programado el próximo reintento o la próxima inspección de disponibilidad. No es una promesa de resultado a esa hora.	null

Cuando se sabe que una fuente de datos está caída, la verificación no espera a su plazo: termina antes con un veredicto parcial que indica por qué (vea partial_reasons y degraded_sources en Verificaciones de dirección) y responde una sola vez.

Sondear una verificación

GET /v1/checks/{check_id} con el scope checks:read.

• Un id pending nunca responde 404. Se resuelve de inmediato con status: "pending". Un 404 significa que el id no es suyo, pertenece al otro entorno o nunca existió.
• Sondee no antes de next_attempt_at. No cambia nada entre las inspecciones programadas. Cuando es null, espere unos segundos. El sondeo cuenta contra el límite de la ruta GET, 30 solicitudes por minuto desde una dirección IP de origen; vea Límites de solicitudes y cuotas.
• Deténgase en completed o failed. Ambos son terminales y ningún campo cambia después. Dos lecturas de una verificación terminal devuelven cuerpos idénticos, así que es seguro volver a leerla siempre que necesite el veredicto.
• Deténgase en deadline_at. La verificación queda finalizada para entonces. Si poco después la última respuesta sigue siendo pending, conserve el check_id y vuelva a leerla más tarde en lugar de entrar en un bucle.

Prefiera un webhook cuando pueda: registra un endpoint una vez y recibe una entrega firmada check.completed por cada verificación terminada, de modo que no hay nada que sondear. Mantenga el sondeo como respaldo para una entrega que nunca llega.

curl

curl -s https://api.leeri.ai/v1/checks/$CHECK_ID \
  -H "Authorization: Bearer $LEERI_API_KEY"

Node.js

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function waitForCheck(checkId) {
  for (;;) {
    const response = await fetch(`https://api.leeri.ai/v1/checks/${checkId}`, {
      headers: { Authorization: `Bearer ${process.env.LEERI_API_KEY}` },
    });
    if (response.status === 429) {
      await sleep(Number(response.headers.get('retry-after') ?? 5) * 1000);
      continue;
    }
    if (!response.ok) throw new Error(`poll failed with ${response.status}`);

    const { data } = await response.json();
    if (data.status !== 'pending') return data;

    if (data.deadline_at && Date.now() > Date.parse(data.deadline_at) + 60_000) {
      throw new Error(`check ${checkId} is still pending after its deadline`);
    }
    const next = data.next_attempt_at ? Date.parse(data.next_attempt_at) - Date.now() : 5000;
    await sleep(Math.min(Math.max(next, 2000), 60_000));
  }
}

const check = await waitForCheck(checkId);
console.log(check.status, check.band, check.score);

Python

import os
import time
from datetime import datetime, timezone

import requests


def parse(value):
    return datetime.fromisoformat(value.replace("Z", "+00:00"))


def wait_for_check(check_id):
    while True:
        response = requests.get(
            f"https://api.leeri.ai/v1/checks/{check_id}",
            headers={"Authorization": f"Bearer {os.environ['LEERI_API_KEY']}"},
            timeout=30,
        )
        if response.status_code == 429:
            time.sleep(int(response.headers.get("Retry-After", "5")))
            continue
        response.raise_for_status()

        data = response.json()["data"]
        if data["status"] != "pending":
            return data

        now = datetime.now(timezone.utc)
        if data["deadline_at"] and (now - parse(data["deadline_at"])).total_seconds() > 60:
            raise RuntimeError(f"check {check_id} is still pending after its deadline")
        wait = (parse(data["next_attempt_at"]) - now).total_seconds() if data["next_attempt_at"] else 5
        time.sleep(min(max(wait, 2), 60))


check = wait_for_check(check_id)
print(check["status"], check["band"], check["score"])

Cuando una verificación falla

Una verificación que termina sin veredicto tiene status: "failed", con score, band y los demás campos del veredicto en null. Una verificación fallida nunca se cobra. Si envía una verificación y falla durante la propia solicitud, la respuesta es 422 CHECK_FAILED; status: "failed" es lo que lee cuando consulta una verificación más tarde. Para volver a intentarlo, envíe la verificación como una solicitud nueva con un Idempotency-Key nuevo; vea Idempotencia.

Probar la ruta pending

Una clave sandbox que envía la dirección de prueba 1PENDNGCHECKADDRESSFRSANDBXTEST99 como verificación de dirección BTC siempre responde pending, de modo que puede construir y probar su sondeo y la gestión de webhooks sin esperar una consulta lenta real. Vea Sandbox y live.