specification: API Commons Rate Limits
specificationVersion: '0.1'
schema: https://raw.githubusercontent.com/api-evangelist/interface-research/main/schema/api-commons.yml#/$defs/RateLimits
provider: HashiCorp Vault
providerId: hvault
created: '2026-05-04'
# Provenance stamped 2026-08-11: this artifact was written by the API Evangelist
# bulk sweep dated 2026-05-04, not harvested from the provider. See roadmap#35.
method: generated
modified: '2026-05-05'
reconciled: true
tags:
  - Rate Limiting
  - Secrets Management
  - Security
description: HashiCorp Vault does not enforce a default account-wide rate limit. Operators configure
  Resource Quotas (rate-limit quotas) using a token-bucket algorithm scoped per-node and per-unique-client-IP.
  Quotas can be applied at global, namespace, mount, path, or auth-role level with most-specific
  rule winning. Vault Enterprise additionally supports identity-based rate limits and lease-count
  quotas. Operational maximums (request size, lease count, namespace count) are documented as advisory
  ceilings rather than throttled limits.
sources:
  - https://developer.hashicorp.com/vault/docs/concepts/resource-quotas
  - https://developer.hashicorp.com/vault/docs/internals/limits
  - https://developer.hashicorp.com/vault/api-docs/system/rate-limit-quotas
limits:
  - name: Resource Quota (rate-limit) - token bucket
    scope: node + client_ip
    metric: requests_per_second
    limit: operator-configured (no default)
    notes: Enforced per Vault server node, not cluster-wide. Set via /sys/quotas/rate-limit endpoint.
  - name: Lease Count Quota (Enterprise)
    scope: namespace or mount
    metric: active_leases
    limit: operator-configured
    notes: Enterprise-only. Caps the total active leases per namespace/mount.
  - name: Maximum request size
    scope: cluster
    metric: bytes_per_request
    limit: 33554432
    notes: 32 MiB default; configurable via max_request_size listener parameter.
  - name: Maximum request duration
    scope: cluster
    metric: seconds_per_request
    limit: 90
    timeFrame: second
    notes: 90 seconds default; configurable via max_request_duration.
  - name: Advisory lease ceiling
    scope: cluster
    metric: active_leases
    limit: 256000
    notes: Advisory operational ceiling; performance degrades beyond this. Use lease quotas to enforce.
policies:
  - name: Token-bucket Algorithm
    description: Rate-limit quotas use token-bucket replenishment. The optional block_interval parameter
      can suspend a client for a configurable window after exceeding the bucket.
  - name: Quota Precedence
    description: Most specific quota wins, in order - role > path > mount > namespace > global root.
    longDescription: Rules are evaluated from most specific to least specific (role-on-auth-mount,
      specific path, mount-level, namespace, global root).
  - name: Per-Node Enforcement
    description: Quotas are enforced per Vault server node, not replicated cluster-wide. Behind a
      load balancer, a 100 RPS quota across a 5-node cluster effectively allows ~500 RPS aggregate.
  - name: System Path Exemption
    description: Health and unseal paths (sys/health, sys/unseal, sys/seal-status) are exempt from
      quotas by default. Configurable via the rate_limit_exempt_paths setting.
  - name: Backoff Strategy
    description: Clients should retry with exponential backoff and jitter when receiving a 429-style
      response. Vault returns HTTP 429 for rate-limited requests with optional Retry-After header
      when block_interval is configured.
  - name: Identity-Based Rate Limiting (Enterprise)
    description: Vault Enterprise can apply rate limits keyed on identity entity rather than client
      IP, useful when many clients share an egress IP.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com