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: Linkerd
providerId: linkerd
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
  - Service Mesh
  - Kubernetes
  - Observability
description: Linkerd does not run as a SaaS — APIs are exposed on cluster (proxy admin on port 4191 per
  pod, control-plane gRPC services). There is no provider-side rate limit on Linkerd's APIs themselves;
  throughput is bounded by your Kubernetes cluster's CPU / memory / network. Linkerd does enforce circuit-breaking
  and retry budgets on the data plane; those are the rate-limit-like primitives users typically configure.
sources:
  - https://linkerd.io/2/reference/architecture/
  - https://linkerd.io/2/features/circuit-breaking/
  - https://linkerd.io/2/features/retries-and-timeouts/
responseCodes:
  circuitOpen: 503
  retriesExhausted: 504
limits:
  - name: Proxy admin API (per pod)
    scope: pod
    metric: requests_per_second
    limit: bounded by pod resource budget
    notes: Admin server on port 4191 per meshed pod. No documented hard rate cap; bound by CPU / memory
      allocated to the proxy container.
  - name: Control-plane gRPC APIs (Destination / Identity / Policy)
    scope: cluster
    metric: requests_per_second
    limit: bounded by control-plane replica count and resource budget
    notes: Scale by adding control-plane replicas; not throttled by Linkerd itself.
  - name: Data-plane retry budget
    scope: service
    metric: retry_ratio
    limit: '0.2'
    notes: Default retry budget is 20% of original request rate. Configurable via ServiceProfile / HTTPRoute
      retryBudget.
  - name: Circuit breaker (failure_accrual)
    scope: endpoint
    metric: consecutive_failures
    limit: '7'
    notes: Default failure_accrual breaks an endpoint after a rolling window of consecutive 5xx responses;
      tunable per ServiceProfile.
policies:
  - name: Self-hosted, no provider quota
    description: Linkerd runs in your cluster; there is no Buoyant- or Linkerd-side per-call quota. Cluster
      capacity is the limit.
  - name: Retry budget over fixed retries
    description: Linkerd uses retry budgets (ratio of retries to original requests) rather than per-request
      max-retry counts to prevent retry storms.
  - name: Circuit breaking
    description: failure_accrual circuit breaker takes failing endpoints out of rotation; configure per-route
      via HTTPRoute / ServiceProfile.
  - name: Timeouts
    description: Per-route timeouts via HTTPRoute / ServiceProfile prevent slow upstreams from holding
      proxy resources.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com