Límites de solicitudes y cuotas

Dos mecanismos distintos limitan el uso de la API: los límites de solicitudes acotan cuántas solicitudes puede enviar por minuto, y la cuota y el saldo pagan las verificaciones que ejecuta. Fallan de manera distinta, así que conviene tratarlos de manera distinta.

Límites de solicitudes

Los límites se cuentan por minuto y por separado para cada combinación de llamante, método HTTP y ruta: consultar GET /v1/checks/{check_id} no consume su margen de POST /v1/checks. Cada solicitud pasa por dos topes, y el primero que se alcanza responde 429.

Tope	Límite por minuto
Por dirección IP de origen (los clientes IPv6 se cuentan por red /64)	30
Por clave de API live	60
Por clave de API sandbox	10
Autenticación fallida, por dirección IP de origen	5
Rederive, por cuenta entre todas sus claves	20
Informes de direcciones, por cuenta entre todas sus claves	10

Los topes se aplican a cada ruta por separado. Por ejemplo, un único servidor que envía todas sus solicitudes live desde una misma dirección IP alcanza el tope de IP de 30 por minuto antes que el tope de clave de 60 por minuto. Para verificar más por minuto, reparta el tráfico entre varias direcciones o envíe hasta 100 verificaciones en una sola solicitud POST /v1/checks/batch, que cuenta como una. Si su volumen necesita límites más altos, escriba a hello@leeri.ai.

Una solicitud limitada responde 429 con RATE_LIMIT_EXCEEDED y estos encabezados:

Encabezado	Significado
Retry-After	Segundos hasta que se reinicia la ventana.
RateLimit-Limit	Solicitudes permitidas por ventana para este llamante, método y ruta.
RateLimit-Remaining	Solicitudes que quedan en la ventana actual.
RateLimit-Reset	Segundos hasta que se reinicia la ventana.

Espere Retry-After segundos y envíe de nuevo la misma solicitud. Demasiadas autenticaciones fallidas desde una dirección también responden 429 durante el resto del minuto, así que una clave incorrecta en un bucle de reintentos bloquea esa dirección: deténgase ante un 401.

curl

curl -s -i -X POST https://api.leeri.ai/v1/checks \
  -H "Authorization: Bearer $LEERI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"address","asset":"TRX","address":"'"$ADDRESS"'"}' | grep -i -E '^(HTTP|retry-after|ratelimit)'

Node.js

async function postWithRetry(url, options) {
  for (let attempt = 1; attempt <= 4; attempt += 1) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;
    const wait = Number(response.headers.get('retry-after') ?? 1);
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
  throw new Error('still rate limited after 4 attempts');
}

Python

import time

import requests


def post_with_retry(url, **kwargs):
    for _ in range(4):
        response = requests.post(url, timeout=30, **kwargs)
        if response.status_code != 429:
            return response
        time.sleep(int(response.headers.get("Retry-After", "1")))
    raise RuntimeError("still rate limited after 4 attempts")

Cómo se paga una verificación

En cada período de facturación su plan incluye un número de verificaciones, su cuota. Una verificación se paga en este orden:

1. Con la cuota restante.
2. Cuando la cuota se agota, con el saldo prepagado, al precio por verificación de su plan.
3. Cuando ambos están agotados, la solicitud se rechaza con 402 INSUFFICIENT_BALANCE y no se ejecuta ninguna verificación.

Un lote se admite completo o no se admite: si la cuota y el saldo no cubren todos los elementos, se rechaza el lote entero. Los planes y precios están en la página de precios.

Qué no se cobra

• Una reverificación en 7 días. Si se le cobró por la misma dirección en la misma cadena en los últimos 7 días, volver a verificarla es gratis, ya sea como verificación de dirección o de transacción. Así puede volver a evaluar a un cliente sin pagar dos veces.
• Verificaciones sandbox. Una clave sandbox nunca consume cuota ni saldo. Vea Sandbox y live.
• Solicitudes rechazadas y fallidas. Un activo no admitido, un error de validación, una verificación fallida y RULESET_UNAVAILABLE nunca se cobran.
• Un veredicto parcial causado por una fuente de datos no disponible. Si una fuente de la que depende el veredicto no estaba disponible o estaba desactualizada, el veredicto lo indica en partial_reasons y se devuelve el cargo: reintentar más tarde puede completarlo.

Qué se cobra

Un veredicto completo se cobra. También se cobra un veredicto parcial cuyo límite es una cota declarada del análisis y no una caída, como un límite del recorrido o la profundidad de solo contrapartes directas en Ethereum, BNB Smart Chain y Base. Ese veredicto es el servicio completo para esa dirección y volver a ejecutarlo no cambia nada.

El informe de evidencias forma parte de la verificación y nunca se factura por separado. El cargo se liquida cuando la verificación termina, así que una verificación en estado pending no es definitiva hasta que se completa.

Capacidad

Las verificaciones live que necesitan una fuente de datos de terceros retienen capacidad hasta que terminan sus consultas. Si la capacidad de su cuenta está llena, la solicitud responde 429 PROVIDER_CAPACITY_EXCEEDED con Retry-After: 30; no se acepta ni se cobra nada, así que reintente tras el intervalo. La capacidad predeterminada admite 100 verificaciones live esperando fuentes de datos a la vez, lo que siempre alcanza para un lote completo de 100.

Una única solicitud que necesita más capacidad de la que la cuenta tiene en total responde 422 PROVIDER_CAPACITY_REQUEST_TOO_LARGE. Nunca puede tener éxito y no lleva Retry-After: envíe menos elementos por solicitud.

Vea Errores para todos los códigos y Sandbox y live para el tope más bajo de sandbox.