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:
| Campo | Qué limita |
|---|---|
limites.api_rpm | Peticiones 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.concurrency | Operaciones en curso al mismo tiempo con una misma clave. |
limites.max_api_keys | Claves 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:
| Cabecera | Qué indica |
|---|---|
RateLimit-Limit | Peticiones por minuto admitidas. |
RateLimit-Remaining | Peticiones que quedan antes de agotar el cupo. |
RateLimit-Reset | Segundos 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
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.