Saltar al contenido
Vintu API
Tema de la documentación
Ir a la app

Límites de uso

La API limita las peticiones por minuto y las operaciones simultáneas. Los valores dependen de tu plan y los devuelve GET /v1/cuenta en limites:

CampoQué limita
limites.api_rpmPeticiones por minuto. Se cuentan por clave y por cuenta a la vez: varias claves de la misma cuenta comparten el cupo de la cuenta.
limites.concurrencyOperaciones en curso al mismo tiempo con una misma clave.
limites.max_api_keysClaves activas que admite la cuenta.

Consulta esos valores en tu cuenta en vez de fijarlos en el código: si cambias de plan, cambian.

Las cabeceras de cada respuesta

Toda respuesta a una petición con clave lleva el estado del cupo:

CabeceraQué indica
RateLimit-LimitPeticiones por minuto admitidas.
RateLimit-RemainingPeticiones que quedan antes de agotar el cupo.
RateLimit-ResetSegundos hasta que el cupo se recupera.

El cupo se recupera de forma continua, no de golpe al cambiar de minuto. Si RateLimit-Remaining llega a 0, espera los segundos de RateLimit-Reset antes de seguir.

Al superar el límite: 429

Respuesta (datos ficticios)HTTP
HTTP/1.1 429 Too Many Requests
Retry-After: 4
RateLimit-Remaining: 0
X-Request-ID: 00000000-0000-4000-8000-000000000002

{"error": {"codigo": "RATE_LIMITED", "mensaje": "Se alcanzó el límite de solicitudes.", "id_peticion": "00000000-0000-4000-8000-000000000002"}}

Espera los segundos de Retry-After y repite la petición. Si vas a hacer muchas seguidas, como en una carga inicial, usa limite=100 en los listados: una página de 100 cuesta lo mismo que una de 25.

Descargas de archivos

Las descargas cuentan contra el cupo general y además contra uno propio, más bajo: la mitad de limites.api_rpm, con un máximo de 30 por minuto. En una descarga, RateLimit-Limit muestra el menor de los dos.

Servicio no disponible: 503

Un 503 es un fallo pasajero de nuestro lado (DEPENDENCY_UNAVAILABLE o LOCAL_CAPACITY). Trae Retry-After: espera esos segundos y reintenta. Pasado un par de intentos, espera más entre uno y otro.

Modo de lectura degradado

Si un componente interno de coordinación falla, la API sigue respondiendo las lecturas con límites más estrictos y lo indica con la cabecera X-Vintu-Mode: lectura_degradada. No hace falta hacer nada: los 429 de ese periodo se tratan igual, esperando Retry-After.