09 — Límites de tasa

Cabeceras en cada respuesta

Toda respuesta autenticada por clave de API incluye:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1747051200

El límite se cuenta por clave de API, no por tenant ni por IP — si un negocio usa varias claves, cada una tiene su propio contador independiente. Un integrador que atiende a muchos comercios desde un mismo servidor no comparte un cupo por IP: cada clave responde por el plan de su comercio.

GET /v1/me no consume el límite: informa en estas cabeceras cuánto llevas en el minuto sin sumar la consulta.

Límite según el plan

Con límite 0, toda solicitud con una clave del comercio responde 429 con details.limit: 0 (pasa si el comercio bajó a un plan sin API después de crear la clave).

Si tu integración necesita más volumen del que tu plan permite, la solución es cambiar de plan (POST /v1/subscription/change), no repartir la carga entre varias claves — eso sería evadir el límite, no resolverlo, y el soporte de Yallegó puede detectarlo.

Al exceder el límite

// 429 Too Many Requests — Retry-After: 43
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Se superó el límite de solicitudes.",
    "details": { "limit": 300, "window_seconds": 60, "retry_after": 43, "scope": "plan" },
    "request_id": "b7f3a2e1-..."
  }
}

Respeta la cabecera Retry-After (en segundos) antes de reintentar — un cliente que reintenta inmediatamente tras un 429 solo prolonga el bloqueo.

details.scope dice qué límite se superó: plan es el límite por minuto de la clave; route, el tope propio de una ruta costosa (abajo).

Tope propio de la exportación

POST /v1/transactions/export genera hasta 10 000 filas por llamada, así que además del límite del plan tiene su propio tope: 10 exportaciones por minuto y por clave. Al superarlo responde 429 con details.scope: "route" y Retry-After. Las demás rutas solo cuentan contra el límite del plan.

Límite por IP

Las solicitudes con una clave de API válida no cuentan contra ningún límite por IP. Ese límite (60 solicitudes por minuto, IP y ruta; 180 en GET /v1/transactions, /summary y /counts) queda para lo que no se autentica con una clave:

• Solicitudes sin credencial.
• Solicitudes con una clave inválida, revocada o vencida: siguen contando contra la IP, así que probar claves al azar no es una vía sin límite.
• La sesión del panel.

Si recibes un 429 con una clave que creías válida, revisa primero que no haya sido revocada o haya vencido (GET /v1/me responde 401 en ese caso).

Una salvedad: si desde una misma IP llegan más de 30 claves inválidas en un minuto, durante ese minuto una clave válida que no se usó en el último minuto cuenta contra la IP en su primera solicitud, hasta que Yallegó la verifica. Evita reintentar en bucle con claves revocadas.

Otros límites, fuera de la API pública

Estos aplican a superficies distintas de la que cubre esta guía, pero conviene conocerlos si tu integración también toca autenticación de panel:

Recomendaciones

• Implementa retroceso exponencial (exponential backoff) en tu cliente para el caso general, no solo para 429 — reduce la carga sobre tu propia integración si la API responde lento.
• Si necesitas sincronizar grandes volúmenes históricos (por ejemplo, al integrarte por primera vez), usa GET /v1/transactions/summary para totales agregados antes de paginar el detalle completo con GET /v1/transactions, y respeta has_more/next_cursor en vez de reconstruir la paginación por offset.
• Prefiere webhooks sobre polling siempre que el caso de uso lo permita (04 — Webhooks) — no consumen tu cupo de límite de tasa porque son solicitudes salientes de Yallegó hacia ti, no al revés.