Rate limits¶
The /v1 API limits request rates so that one client's use does not degrade the service for
the others. This page explains how the limits work and how to adapt your client; it does not
publish the per-tier figures, which depend on your licence and may change without notice.
What is limited¶
Each limit counts requests in a fixed one-minute window. Three limits apply:
Scope (details.scope) |
What it counts |
|---|---|
key |
The requests of one credential |
tenant |
Those of your whole organisation, all its keys together |
service |
Those of the service as a whole |
The first two come from the licence of your organisation: a higher licence tier has more room, and an MSSP partner has more than a direct customer of the same tier. Your organisation's use never counts against another's.
A portfolio (MSSP) key is limited per key (portfolio_key), per provider across all its
portfolio keys (portfolio_org) and per service; once the selected client tenant is known, that
tenant's own limit (tenant) and the provider's share of it (portfolio_tenant) apply too.
Headers¶
Every response that got past authentication carries the limit closest to being exhausted:
| Header | Meaning |
|---|---|
RateLimit-Limit |
Requests allowed in the window |
RateLimit-Remaining |
Requests left in the current window |
RateLimit-Reset |
Seconds until the window renews |
RateLimit-Policy |
<limit>;w=<window seconds> |
Read the current limit from RateLimit-Limit and RateLimit-Policy instead of hard-coding it.
The figures per tier are not published on this page on purpose: they follow the licence of your organisation and may change without notice, so any number written here would go stale. The headers above always carry the values that apply to you at that moment.
When it runs out: 429¶
The answer is 429 with error.code: "rate_limited", the Retry-After header (in seconds)
and error.details.scope saying which limit was exhausted. Wait Retry-After before retrying,
with exponential backoff if it happens again (see Errors).
Because windows are fixed, a client can send up to twice the limit across two consecutive
windows: do not pace to the second, respect Retry-After.
The HodeiShield CLI retries short waits on its own and, if the limit is still exhausted, exits with code 6 (see CLI).
Plan quotas¶
API rate limits are different from your plan quotas (number of vendors, assets, users, AI messages and simulations). Those quotas are shown in the console and described in the documentation of each plan; this page does not repeat them.
Limits are not part of the frozen contract¶
They belong to the service, not to the frozen /v1 contract: they may be raised without
notice. See Versioning and deprecation.
Discovery¶
The API publishes an RFC 9727 API catalog at
https://api.hodeishield.com/.well-known/api-catalog
(application/linkset+json). It points to the OpenAPI description of /v1 (service-desc) and
to this documentation (service-doc), so a client can find both from the host alone.