Límites de uso¶
La API /v1 aplica límites de peticiones para que el uso de un cliente no degrade el servicio
de los demás. Esta página explica cómo funcionan y cómo adaptar tu cliente; no publica las
cifras por nivel, que dependen de tu licencia y pueden cambiar sin aviso.
Qué se limita¶
Cada limitación cuenta las peticiones en una ventana fija de un minuto. Se aplican tres límites:
Ámbito (details.scope) |
Qué cuenta |
|---|---|
key |
Las peticiones de una misma credencial |
tenant |
Las de toda tu organización, todas sus claves juntas |
service |
Las del servicio en conjunto |
Los dos primeros dependen de la licencia de tu organización: un nivel de licencia mayor tiene más margen, y un socio MSSP tiene más que un cliente directo del mismo nivel. El uso de tu organización nunca cuenta contra el de otra.
Una clave de cartera (MSSP) se limita por clave (portfolio_key), por proveedor entre todas sus
claves de cartera (portfolio_org) y por servicio; cuando el inquilino cliente seleccionado ya
está identificado, se aplican además el límite propio de ese inquilino (tenant) y la parte del
proveedor en él (portfolio_tenant).
Cabeceras¶
Toda respuesta que pasó la autenticación lleva el límite más cercano a agotarse:
| Cabecera | Significado |
|---|---|
RateLimit-Limit |
Peticiones permitidas en la ventana |
RateLimit-Remaining |
Peticiones que quedan en la ventana actual |
RateLimit-Reset |
Segundos hasta que la ventana se renueva |
RateLimit-Policy |
<límite>;w=<segundos de la ventana> |
Lee el límite actual de RateLimit-Limit y RateLimit-Policy en lugar de fijarlo en tu
código.
Las cifras por nivel no se publican en esta página a propósito: dependen de la licencia de tu organización y pueden cambiar sin aviso, así que cualquier número escrito aquí quedaría desfasado. Las cabeceras de arriba llevan siempre los valores que te aplican en ese momento.
Cuando se agota: 429¶
La respuesta es 429 con error.code: "rate_limited", la cabecera Retry-After (en segundos)
y error.details.scope indicando cuál de los límites se agotó. Espera Retry-After antes de
reintentar, con backoff exponencial si vuelve a ocurrir (ver Errores).
Como las ventanas son fijas, un cliente puede llegar a enviar hasta el doble del límite a
caballo de dos ventanas consecutivas: no te ajustes al segundo, respeta Retry-After.
La CLI de HodeiShield reintenta esperas cortas por sí sola y, si el límite sigue agotado, sale con el código 6 (ver CLI).
Cuotas del plan¶
Los límites de uso de la API son distintos de las cuotas de tu plan (número de proveedores, activos, usuarios, mensajes de IA y simulaciones). Esas cuotas se consultan en la consola y se describen en la documentación de cada plan; esta página no las repite.
Los límites no son parte del contrato congelado¶
Forman parte del servicio, no del contrato /v1 congelado: pueden subir sin aviso. Ver
Versionado y deprecación.
Descubrimiento¶
La API publica un catálogo de API según el RFC 9727 en
https://api.hodeishield.com/.well-known/api-catalog
(application/linkset+json). Apunta a la descripción OpenAPI de /v1 (service-desc) y a esta
documentación (service-doc), de modo que un cliente encuentra ambas a partir del solo host.