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 Cloud Platform
providerId: hcp
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:
  - Cloud
  - Infrastructure
  - DevOps
  - Secrets Management
  - Service Networking
  - Rate Limiting
  - Quotas
  - Throttling
description: HCP enforces API rate limits per authenticated user (or per IP for unauthenticated
  requests). The headline limit for HCP Terraform is ~30 requests/second across most endpoints.
  Sensitive endpoints have stricter ceilings — SMS/2FA at 5 requests/minute, email-sending at
  10–100 requests/minute (per endpoint), and certain account operations at 40 requests/hour. Limits
  are scoped per user, so multiple tokens issued to the same user share the budget. Other HCP
  products (Vault, Consul, Boundary, Packer, Waypoint) inherit the HCP platform throttling layer.
sources:
  - https://developer.hashicorp.com/terraform/cloud-docs/api-docs
headers:
  limit: x-ratelimit-limit
  retryAfter: Retry-After
responseCodes:
  throttled: 429
  quotaExceeded: 429
  serviceUnavailable: 503
limits:
  - tier: all
    name: HCP Terraform — Default API rate
    scope: user-or-ip
    metric: requests_per_second
    limit: 30
    timeFrame: second
    applies:
      - HCP Vault Secrets API
      - HCP Packer API
      - HCP Consul API
      - HCP Boundary API
      - HCP Waypoint API
    notes: Documented for HCP Terraform; other HCP products share the platform throttling layer.
  - tier: all
    name: SMS / 2FA endpoints
    scope: user
    metric: requests_per_minute
    limit: 5
    timeFrame: minute
    applies:
      - HCP Vault Secrets API
      - HCP Packer API
      - HCP Consul API
      - HCP Boundary API
      - HCP Waypoint API
  - tier: all
    name: Email-sending endpoints
    scope: user
    metric: requests_per_minute
    limit: '10–100'
    timeFrame: minute
    applies:
      - HCP Vault Secrets API
      - HCP Packer API
      - HCP Consul API
      - HCP Boundary API
      - HCP Waypoint API
    notes: Specific endpoints fall in the 10–100/min band; verify per-endpoint.
  - tier: all
    name: Account operations
    scope: user
    metric: requests_per_hour
    limit: 40
    timeFrame: hour
    applies:
      - HCP Vault Secrets API
      - HCP Packer API
      - HCP Consul API
      - HCP Boundary API
      - HCP Waypoint API
policies:
  - name: Per-User Scoping
    description: Rate limits are scoped per authenticated user, not per token — multiple tokens
      issued to the same user share the limit budget.
  - name: Backoff Strategy
    description: On HTTP 429 with the JSON-API error 'You have exceeded the API's rate limit',
      back off and retry with jitter; honor Retry-After when present.
  - name: Sensitive Endpoint Throttling
    description: SMS/2FA, email, and account-mutation endpoints have tighter ceilings than the
      default 30 rps; design clients accordingly.
  - name: Unauthenticated Requests
    description: Unauthenticated requests are bucketed by source IP rather than user.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com