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 Nomad
providerId: nomad
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
  - Workload Orchestration
  - DevOps
description: The Nomad HTTP API does not enforce HTTP-level rate limits in the open-source distribution.
  Throughput is bound by Nomad server capacity (Raft commit, scheduler workers, RPC concurrency) and
  client-side ACL token limits. Nomad supports blocking queries and long-poll consistency modes that
  control how clients consume the API. Rate-limit-style protections are configured operator-side via
  ACL token hierarchies, namespaces, and Sentinel policies (Enterprise).
sources:
  - https://developer.hashicorp.com/nomad/api-docs
responseCodes:
  badRequest: 400
  forbidden: 403
  notFound: 404
  serverError: 500
limits:
  - name: Nomad HTTP API
    scope: server
    metric: varies
    limit: bound by server CPU, memory, Raft commit rate
    notes: No per-second HTTP rate limit enforced; throughput is implementation-bounded.
  - name: Blocking queries
    scope: per-request
    metric: long-poll-duration
    limit: 5 minutes (default wait)
    notes: Clients can long-poll via index= and wait= parameters; `wait` defaults to 5 minutes, capped
      at 10 minutes.
  - name: Pagination
    scope: per-request
    metric: per_page
    limit: 100 (default)
    notes: Use `next_token` for cursor-based pagination on list endpoints.
  - name: ACL token enforcement
    scope: token
    metric: varies
    limit: token-policy-bound
    notes: ACL policies bound which endpoints / namespaces / nodes a token can reach.
policies:
  - name: Blocking queries / consistency modes
    description: Use index= and wait= parameters for long-poll behavior; choose `stale` consistency for
      reads to spread load across followers and reduce leader pressure.
  - name: Pagination
    description: Use `next_token` cursor pagination; do not enumerate all jobs / allocations in a single
      request.
  - name: ACL token scoping
    description: Issue narrowly scoped ACL tokens per integration; revoke unused tokens promptly.
  - name: Sentinel governance (Enterprise)
    description: In Enterprise, Sentinel policies can rate-limit operations like job submissions per
      namespace.
  - name: Namespaces (Enterprise)
    description: Use namespaces to isolate teams and prevent noisy-neighbor scheduler pressure.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com