Límites de Velocidad
La API de VaultPAM aplica límites de velocidad por cliente para proteger la estabilidad del servicio. Todas las respuestas de la API incluyen encabezados x-ratelimit-* para que su cliente pueda rastrear su consumo actual y retroceder gradualmente antes de alcanzar un límite.
Encabezados de Respuesta
Cada respuesta de la API incluye los siguientes encabezados:
| Encabezado | Tipo | Descripción |
|---|---|---|
x-ratelimit-limit | entero | Número máximo de solicitudes permitidas en la ventana actual |
x-ratelimit-remaining | entero | Solicitudes restantes en la ventana actual |
x-ratelimit-reset | Timestamp Unix (segundos) | Cuándo se reinicia la ventana actual |
En una respuesta 429 Too Many Requests, se incluye un encabezado adicional:
| Encabezado | Tipo | Descripción |
|---|---|---|
retry-after | entero (segundos) | Tiempo mínimo a esperar antes de reintentar |
Todos los encabezados utilizan nombres en minúsculas.
Categorías de Límites de Velocidad
La API aplica diferentes límites según el tipo de operación y el contexto de llamada. Los encabezados x-ratelimit-* en cada respuesta reflejan la categoría de límite aplicable a esa solicitud específica.
Valores de referencia (solo orientación — trate los encabezados x-ratelimit-* como autoritativos):
| Categoría | Límite |
|---|---|
| Intentos de inicio de sesión por IP | 60 por minuto |
| Solicitudes de API por IP | 300 por minuto |
| Solicitudes de API por usuario autenticado | 120 por minuto |
| Operaciones sensibles por usuario | 30 por minuto |
Los límites mostrados arriba documentan los valores predeterminados actuales. Utilice los valores x-ratelimit-limit y x-ratelimit-remaining en cada respuesta para tomar decisiones de reintento — los números publicados pueden cambiar sin previo aviso.
Manejo de Respuestas 429
Cuando reciba una respuesta 429 Too Many Requests:
- Lea el valor del encabezado
retry-after(segundos). - Pause su bucle de solicitudes durante al menos esa duración.
- Reintente la solicitud.
Respuesta de ejemplo:
HTTP/1.1 429 Too Many Requests
x-ratelimit-limit: 120
x-ratelimit-remaining: 0
x-ratelimit-reset: 1747483200
retry-after: 37
Content-Type: application/json
{
"error": "RATE_LIMITED",
"message": "Too many requests. Retry after 37 seconds."
}
Patrones de Cliente Recomendados
Verificar presupuesto disponible antes de operaciones en lote
Lea x-ratelimit-remaining después de cada respuesta. Si disminuye por debajo de un umbral (por ejemplo, 10), introduzca una pausa antes de la siguiente solicitud para evitar activar un 429.
Retroceso exponencial para 429s transitorios
Si retry-after no está presente o recibe múltiples respuestas 429 consecutivas, utilice retroceso exponencial con jitter:
wait = min(base * 2^attempt + random_jitter, max_wait)
Registrar x-ratelimit-reset para depuración
Cuando diagnostique problemas de límite de velocidad, registre el timestamp Unix x-ratelimit-reset junto con la respuesta. Convierta a una hora legible para entender cuándo se reinicia la ventana.
Pasos Siguientes
- Flujo de Autenticación — adquiera tokens antes de realizar llamadas a la API
- Inicio Rápido curl — vea los encabezados de límite de velocidad en acción