Hermos API
Concepts

Rate limits

Current middleware buckets and response headers.

The general-purpose limiter uses fixed one-minute windows aligned to epoch minute boundaries. Each HTTP request costs one unit. Denied requests do not spend allowance.

BucketLimit per minuteScope
checkoutPreflight120Transport address and company, across checkout preflight origins.
preAuth3000Transport address, before authentication.
global20000Whole API instance, after the per-address gate.
priceChangeCancel30Separately per transport address and per notice token hash, shared by lookup and confirm.
default300Stable principal ID.
staff_directory20Authenticated session user ID; admission before staff lookup, at most four concurrent directory reads per instance.
companyReference60Stable member ID, across sessions and references.
entitlement3000Stable principal ID.
bookkeeping600Stable principal ID.
mcp_denials60Stable agent ID.
customer_activity600Stable principal ID.
customer_search30Stable principal ID.
payments_export10Stable principal ID.
customer_search_company60Company and mode, shared by every key and member session
publishableKey10000Publishable key, across all of its browsers.

Checkout preflights spend their dedicated budget before origin lookups. Allowed and unknown origins receive empty HTTP 204 responses; only registered origins receive credentialed CORS headers. Those headers necessarily reveal whether a browser may proceed, so the bucket bounds unauthenticated probing instead of claiming complete indistinguishability. Each syntactically valid origin lookup reads both the platform host and company domain tables. Actual requests still recheck the origin against the verified key's company.

Cross-origin preflight covers only opening or creating a checkout instance (GET or POST /v1/checkout_instances) and reading one (GET /v1/checkout_instances/{id}). The payment steps — submit, resume, complete and return under /v1/checkout_instances/{id}/ — are same-origin only: Hermos's hosted checkout pages call them through their own origin, and a preflight for any of them receives no CORS headers, so browsers on other origins cannot call them.

Allowed preflights include Access-Control-Max-Age: 600. The 120/minute allowance per address and company lets 15 buyers behind one NAT each warm eight URL caches in a minute; cached preflights then avoid repeat probes for ten minutes. Other companies have separate allowances. This provides shared-address headroom, not an unlimited-traffic guarantee.

After exhaustion, a 429 includes credentialed CORS headers only for an origin already verified for that same address and company during the current window. The API retains at most 1,024 such decisions per resolver, evicting the oldest; expired, evicted, newly seen and unknown origins receive no CORS headers. No over-budget request performs a domain lookup or extends a decision's lifetime. A fresh in-budget denial removes the cached decision. Only successful 204 preflights receive Max-Age. A non-success OPTIONS response can still be reported as a preflight failure by browsers even when it carries CORS headers.

OAuth requests also pass dedicated buckets. The oauthRegisterDaily bucket uses a daily window; the other OAuth buckets use one-minute windows.

BucketLimit per windowScope
oauthAuthorize30Transport address, authorization requests.
oauthTokenFailure120Transport address, failed token requests.
oauthTokenSuccess30Connection, successful token requests.
oauthRegisterRejected10Transport address, rejected client registrations.
oauthRegister60Transport address and assistant, client registrations.
oauthRegisterDaily600Transport address and assistant, client registrations per day.

GET /v1/customers?q= uses customer_search: 30 searches per minute. The same route without q stays on default. All of a merchant's keys share 60 searches per minute per mode on top of the 30 per key through customer_search_company.

POST /v1/customers/{id}/activity uses customer_activity: 600 requests per minute. Each request can contain 1–100 events. A separate persisted cap permits 5,000 new events per customer per UTC day; duplicates do not consume that cap.

Route policy selects the principal bucket. Worker principals skip the principal limiter; all HTTP traffic except /health passes the pre-authentication gate, then the instance-wide global ceiling. The per-address gate runs first, so one noisy address is refused before it can consume the shared ceiling. No request body is read before either decision. Credential renewal does not reset a stable principal's budget. Public entitlement and bookkeeping endpoints are not yet available. The current limiter stores counters in process; a deployment-wide shared limiter is not yet available.

Publishable-key requests are attributed to the browser or checkout calling with the key, not the key itself, so each browser gets its own default budget. The publishableKey bucket is an additional ceiling shared by every browser using one publishable key; it survives key renewal. Requests from a browser already bound to a checkout instance do not count toward it, so traffic from other browsers cannot block a checkout in progress. A first checkout open with no browser binding is limited by the preAuth gate and the publishableKey bucket.

Customer sign-in requests (POST /v1/customer_sign_in_links and its verify_code route) also pass dedicated buckets with fixed 15-minute windows. The transport-address bucket is checked first.

BucketLimit per 15 minutesScope
signInLinkIp20Transport address, link requests across all companies.
signInLinkAddress5Sign-in email address within one company.
signInLinkCompany300Company, link requests across all addresses.
signInCodeIp30Transport address, code checks across all companies.
signInCodeAddress10Sign-in email address within one company, code checks.

Reissuing a customer sign-in link also uses the shared signInLinkIp budget and two dedicated buckets with their own windows. A request that exceeds a bucket still receives the same sent_if_matched response without sending a link.

BucketLimit per windowScope
signInLinkReissueLink1Sign-in link within one company and mode, reissues per 10 minutes.
signInLinkReissueCustomer3Customer within one company and mode, reissues per hour.

Account-binding proof requests (POST /v1/account_binding_proofs) use these dedicated fixed-window buckets. Exhausting one still returns the same HTTP 202 request envelope without sending a proof email. Public proof confirmation shares signInLinkIp.

BucketLimit per windowScope
accountBindingAccount5Company, mode, product and account reference, requests per hour.
accountBindingAddress3Purchase email address within one company, requests per hour.
accountBindingCompany300Company, requests across all addresses per 15 minutes.

The public early-access sign-up (POST /early-access, outside /v1) also spends a dedicated bucket with a fixed 10-minute window, after the shared per-address and global limits. A refused sign-up receives HTTP 429; repeat sign-ups for one address are separately capped at three confirmation emails per hour without changing the response.

BucketLimit per windowScope
early_access10Transport address, early-access sign-ups per 10 minutes.

The internal signInAudit budget caps sign-in audit writes at 60 per minute per company and mode, per API instance; exhausting it suppresses the audit row without changing the response.

The internal rejectedAudit budget caps rejected-auth audit writes at 60 per minute per company and mode, per API instance; exhausting it suppresses the audit row and leaves the response 401. The internal rejectedAuditOutsider budget caps outsider member-refusal audit writes at 60 per minute per company, per API instance, preserving the LIVE member and rejected-auth audit budget. The internal entitlementScopeAudit budget caps out-of-scope entitlement read audit writes at 60 per minute per embed session / per customer, per API instance; exhausting it suppresses the audit row without changing the empty 200 response.

Member refusals first consume the per-user rejectedAudit budget (60 per minute across companies). A user-scoped identity lookup checks the authenticated user's membership in the target company for active status, without filtering company status. Only a proven active membership in the target company shares its LIVE rejectedAudit budget with rejected-auth audits, even if the company is suspended or closed. Everyone else uses rejectedAuditOutsider: missing, invited or removed memberships, and failed membership lookups. Classification never depends on the refusal error. Both budgets must allow the audit write. Exhaustion suppresses the row and emits a structured warning with request ID, user ID, company ID, bucket and suppressed: true, without changing the refusal response. Member 429 responses consume neither audit budget nor an audit transaction.

The pre-authentication gate keys on the transport address. Behind the Fly edge that is the Fly-Client-IP header set by the platform; elsewhere it is the socket address, and other caller-supplied forwarding headers are ignored. Sign-in requests relayed by the Hermos web app use the visitor address the web app vouches for with its proxy secret. IPv6 addresses share a budget per /64 prefix, and IPv4-mapped IPv6 addresses count as their IPv4 address. Requests without usable transport metadata share an unknown bucket.

Response headerMeaning
X-RateLimit-LimitCapacity of the most recent applicable bucket.
X-RateLimit-RemainingRemaining allowance.
X-RateLimit-ResetReset time in Unix epoch seconds.
Retry-AfterOn 429, whole seconds until reset, at least 1.

The middleware reapplies rate headers on errors and idempotent replays. A refused request returns HTTP 429 with rate_limited. Wait for Retry-After before retrying.

Checkout hand-off creation, POST /v1/checkout_handoffs/abandon and POST /v1/checkout_handoffs/{id}/abandon use the default bucket: 300 requests per minute per merchant principal.