Límites de tasa

Cada solicitud está sujeta a dos límites: un límite a nivel de cuenta, que cubre casi todos los endpoints, y, en unos pocos de ellos, un límite propio más estricto. El que alcanzarás es el menor de los dos.

Límite a nivel de cuenta

Se cuenta por cuenta, en una ventana fija de un minuto. Todas las claves API de una misma cuenta comparten un único presupuesto: crear más claves no eleva tu límite.

Quién eres	Límite por defecto
Cuenta con una compra o suscripción previa, o con un saldo de 10 TRX o más	1000 solicitudes/minuto
Cualquier otra cuenta autenticada	300 solicitudes/minuto
Solicitudes sin autenticación	60 solicitudes/minuto por dirección IP
Consulta de `GET /api/v1/invoices/{invoice_id}` sin autenticación	180 solicitudes/minuto por dirección IP

Los presupuestos sin autenticación se cuentan por separado para cada grupo de endpoints — precios, estado de factura, consultas de dirección, autenticación y todo lo demás —, de modo que consultar precios nunca consume el presupuesto del resto. Estos son los valores por defecto. Si tu integración necesita un techo más alto, lo elevamos para tu cuenta: escríbenos por Telegram.

La ventana es fija, no deslizante: el contador se reinicia al comienzo de cada minuto. Pero no montes una ráfaga alrededor de esa frontera. Dos mecanismos independientes hacen que sea mala apuesta. Delante de la API hay un límite de borde de unas 50 solicitudes por segundo y por dirección IP, que responde 503 con cuerpo HTML, no un error JSON. Y una cuenta que se mantiene por encima de su límite durante tres minutos seguidos ve su límite reducido a la mitad los diez minutos siguientes; tres minutos más así la bloquean por completo durante treinta, con Retry-After: 1800. Las cuentas del nivel de 1000/minuto están exentas de esa escalada.

Endpoints con un límite propio más estricto

Endpoint	Límite	Se cuenta por
`POST /api/v1/invoices`	10 solicitudes/minuto	dirección IP
`POST /api/v1/account/withdrawal`	5 s tras un retiro creado con `Idempotency-Key`, 60 s tras uno sin él	cuenta
`POST /api/v1/energy/auto-refill`	10 solicitudes/minuto	cuenta
`POST /api/v1/bandwidth/auto-refill`	10 solicitudes/minuto	cuenta

Ten en cuenta que POST /api/v1/invoices se cuenta por dirección IP, no por cuenta: si varios de tus clientes envían solicitudes desde la misma IP de salida, comparten un único presupuesto de 10 por minuto. Los endpoints de compra — POST /api/v1/energy/buy, POST /api/v1/energy/activate, POST /api/v1/bandwidth/buy y POST /api/v1/bandwidth/rentals — llevan un presupuesto más antiguo de 1000 solicitudes por minuto contado por dirección IP (los dos endpoints de bandwidth comparten uno solo). Para una única cuenta nunca es el límite determinante, pero los clientes tras una misma IP de salida lo comparten entre sí. Los endpoints de gestión de webhooks (/api/v1/webhooks/...) no están cubiertos por el límite a nivel de cuenta. El resto de los endpoints documentados no tiene límite propio: solo se les aplica el límite a nivel de cuenta.

Cómo es una respuesta 429

El cuerpo depende de qué límite hayas alcanzado. Existen tres formas, así que analiza el cuerpo de forma defensiva en lugar de dar por supuesta una de ellas. Límite a nivel de cuenta. La respuesta lleva una cabecera Retry-After con los segundos de espera:

HTTP/1.1 429 Too Many Requests
Retry-After: 37

{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests. Please try again later."}}

Límite del endpoint, por ejemplo en POST /api/v1/invoices. No hay cabecera Retry-After; la ventana es de un minuto:

{"detail":{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests. Please try again later."}}}

POST /api/v1/account/withdrawal. Un detail de texto plano con los segundos restantes, sin código de error:

{"detail":"Rate limit: try again in 42s"}

Un 429 que reintentar no resuelve

POST /api/v1/invoices también responde 429 cuando ya tienes demasiadas facturas sin pagar: como máximo 3 por dirección IP y como máximo 5 por cuenta. El límite por IP también se aplica a las solicitudes autenticadas, por lo que suele ser el primero que alcanzas:

{"detail":"Too many pending invoices (max 3)"}

Es un tope sobre las facturas abiertas, no un límite de tasa, y esperar no lo libera por sí solo. Paga una de las facturas pendientes, o deja que expire, antes de crear otra. El mismo endpoint también reporta fallos transitorios ajenos como 429 — por ejemplo {"detail":"Energy price unavailable"}. Lee el mensaje antes de decidir cómo reaccionar.

Reintentos

Si la respuesta lleva la cabecera Retry-After, espera exactamente esos segundos.
En caso contrario, usa retroceso exponencial empezando en un segundo.
Nunca reintentes de inmediato.
Lee el cuerpo antes de reintentar: Too many pending invoices requiere otra acción, no una espera más larga.

import time
import requests

def post_with_retry(url, **kwargs):
    for attempt in range(3):
        resp = requests.post(url, **kwargs)
        if resp.status_code == 429:
            body = resp.text
            if "pending invoices" in body:
                raise RuntimeError(body)  # esperar no ayudara
            delay = int(resp.headers.get("Retry-After", 2 ** attempt))
            time.sleep(delay)
            continue
        return resp
    raise RuntimeError("Max retries exceeded")

¿Necesitas límites más altos?

Contáctanos por Telegram para límites de tasa personalizados en integraciones de alto volumen.

​Límites de tasa

​Límite a nivel de cuenta

​Endpoints con un límite propio más estricto

​Cómo es una respuesta 429

​Un 429 que reintentar no resuelve

​Reintentos

​¿Necesitas límites más altos?