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: Etcd
providerId: etcd
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: false
tags:
  - Rate Limiting
  - Distributed Systems
  - Key-Value Store
  - Open Source
description: etcd is self-hosted open-source software, so there is no upstream "service" rate limit.
  etcd does enforce its own resource caps (max-request-bytes, quota-backend-bytes, max-concurrent-streams)
  that act as throttling/safety mechanisms; the actual request throughput is limited by hardware (disk
  fsync latency dominates) and by the Raft protocol's serialization of writes. The values below describe
  configurable etcd guardrails rather than a vendor quota.
sources:
  - https://etcd.io/docs/latest/op-guide/configuration/
  - https://etcd.io/docs/latest/op-guide/maintenance/
notes: etcd is operator-tuned; replace these defaults with the values configured for your cluster.
responseCodes:
  resourceExhausted: 8 (gRPC RESOURCE_EXHAUSTED)
  unavailable: 14 (gRPC UNAVAILABLE)
limits:
  - name: max-request-bytes
    scope: server
    metric: bytes_per_request
    limit: 1572864
    notes: Default 1.5 MiB per request; configurable.
  - name: quota-backend-bytes
    scope: cluster
    metric: bytes_storage
    limit: 2147483648
    notes: Default 2 GiB DB quota; raise to 8 GiB max safe; cluster goes read-only when exceeded.
  - name: max-concurrent-streams
    scope: server
    metric: concurrent_streams
    limit: 4294967295
    notes: gRPC max-concurrent-streams; effectively unbounded by default.
  - name: Operator-imposed throttle
    scope: client
    metric: requests_per_second
    limit: operator-defined via client-side rate limiting or proxy
policies:
  - name: Linearizable reads
    description: Linearizable reads require quorum; degrade to serializable reads to lower load when
      consistency tolerates it.
  - name: Compaction and defragmentation
    description: Schedule periodic compaction of revisions and defrag to keep DB size under quota-backend-bytes.
  - name: Backoff
    description: On RESOURCE_EXHAUSTED or UNAVAILABLE, clients should apply exponential backoff with
      jitter and avoid retry storms.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com