Límites de uso

Dos límites distintos

La API tiene dos topes que no hay que confundir:

	Qué es	Qué responde al pasarlo
Saldo de consultas	Cuántas consultas RUNT te quedan compradas	402 Payment Required
Ritmo de peticiones	Cuántas llamadas HTTP aceptamos por minuto y por día	429 Too Many Requests

El primero se recarga comprando una bolsa. El segundo se espera.

Requisitos para usar la API

Dos cosas, ambas obligatorias:

Un plan que incluya API: PyME, PyME Pro o Enterprise. Sin él no se puede emitir una llave y la API responde 403. Los tres se diferencian por el ritmo que admiten: 100, 10.000 y 100.000 peticiones al día.
Saldo de consultas en la billetera de tu organización.

El saldo de consultas

Cada llamada exitosa a POST /consults/vehicle o POST /consults/license descuenta una unidad del saldo. Los endpoints de lectura de tu propia flota (/vehicles, /drivers, /infractions, /expirations) no descuentan nada.

Tres detalles que importan al integrar:

Una consulta fallida no cuesta. Si el RUNT no responde y la API devuelve 503, no se descuenta saldo.

El saldo es de la organización, no de la llave. Todas las llaves de tu organización gastan del mismo saldo. Una integración que se descontrola deja sin saldo a las demás.

Se cobra también la respuesta de caché. Una consulta repetida dentro de las 24 horas se responde del caché y llega mucho más rápido, pero descuenta igual. Si vas a consultar la misma placa varias veces en un proceso, guárdala en memoria.

Sin saldo: 402

{
  "success": false,
  "message": "Sin saldo de consultas. Compra una bolsa para seguir usando el API."
}

Es 402 y no 403 a propósito: 402 significa “recarga y vuelve a intentar”, 403 significa “tu llave no puede hacer esto”. Trátalos distinto.

const res = await fetch(url, { headers: { 'X-API-Key': apiKey } });

if (res.status === 402) {
  // Recargable: avisa a quien administra la cuenta y deja de reintentar.
  await avisarSaldoAgotado();
  return null;
}

Reintentar un 402 no sirve de nada hasta que alguien compre una bolsa.

Comprar saldo

Las bolsas se compran en el panel, en Facturación → Consultas. El saldo no vence.

Bolsa	Precio	Por consulta
1.000	$25.000	$25
5.000	$110.000	$22
20.000	$400.000	$20
100.000	$1.700.000	$17

El límite de peticiones

Son dos topes, y cada uno se cuenta sobre algo distinto:

Plan	Ráfaga por minuto	Techo diario
PyME	60	100
PyME Pro	120	10.000
Enterprise	300	100.000

La ráfaga por minuto es de cada llave. Si una integración tuya se desboca, agota su propia llave y las demás siguen respondiendo.

El techo diario es de la cuenta. Todas las llaves de tu organización gastan del mismo cupo diario, así que emitir llaves nuevas no lo multiplica.

Al pasarte de cualquiera de los dos, la API devuelve 429 con el header Retry-After indicando los segundos que faltan para que la ventana se libere. Si el que se agotó fue el diario, Retry-After te llevará al día siguiente.

Cada respuesta trae X-RateLimit-Limit y X-RateLimit-Remaining con el de los dos topes que en ese momento te deje menos margen: al empezar el día verás la ráfaga, y cerca del techo diario verás la cuota.

Manejar un 429

Respeta Retry-After. Es el número que la API te da; adivinar es peor:

async function pedir(url, apiKey, intentos = 3) {
  for (let i = 0; i < intentos; i++) {
    const res = await fetch(url, { headers: { 'X-API-Key': apiKey } });

    if (res.status !== 429) return res;

    const espera = Number(res.headers.get('Retry-After') ?? 60);
    await new Promise((r) => setTimeout(r, espera * 1000));
  }

  throw new Error('Límite de peticiones excedido tras varios reintentos');
}

Cómo no chocar con el límite

Sube per_page en vez de hacer más llamadas. Recorrer 500 vehículos de 20 en 20 son 25 peticiones; de 100 en 100 son 5.

# Mal: 25 llamadas
curl "https://api.notiauto.co/v1/vehicles?per_page=20"

# Bien: 5 llamadas
curl "https://api.notiauto.co/v1/vehicles?per_page=100"

Usa /expirations en vez de calcular vencimientos tú. Una llamada te da SOAT, tecnomecánica y licencias con los días restantes ya calculados, en vez de traer todos los vehículos y todos los conductores para hacer la resta.

Aprovecha el caché de las consultas RUNT. Una consulta repetida dentro de las 24 horas se sirve del caché y no golpea al RUNT, pero sí cuenta para tu límite de peticiones. Si vas a consultar la misma placa varias veces en el mismo proceso, guarda el resultado en memoria. Ver Consultas RUNT y caché.

No hagas polling agresivo. Los datos de flota cambian por sincronizaciones programadas, no en tiempo real. Consultar cada minuto no te va a dar información más fresca que consultar cada hora.

Las consultas RUNT y el ritmo

POST /consults/vehicle y POST /consults/license se rigen por los mismos dos topes que el resto de endpoints. Lo que las distingue es que además gastan saldo.

Cada consulta que llega al RUNT es una llamada a un servicio externo, lenta y con costo. Por eso el caché de 24 horas por identidad: una consulta repetida dentro de esa ventana se responde del caché y no llega al RUNT. Ver Consultas RUNT y caché.

El cupo del panel no es el saldo del API

Tu plan incluye un cupo anual de consultas para el módulo Consultas del panel (120 al año en Individual, 500 en PyME, 1.500 en PyME Pro). Ese cupo no aplica al API: por API cada consulta sale del saldo prepago desde la primera.

Lo que el plan sí decide para tu integración es si puedes emitir llaves y con qué nivel de límite. Ver Planes y facturación.