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: Kuma
providerId: kuma
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
  - Open Source
description: Kuma's control-plane REST API has no vendor-imposed rate limit — it runs in-cluster (Kubernetes
  or Universal) and is bound by the operator's own deployment. Kuma does, however, ship a configurable
  data-plane RateLimit policy (MeshRateLimit / RateLimit) that consumers apply to mesh traffic between
  services. That is a feature of the mesh, not a quota imposed on the user.
sources:
  - https://kuma.io/docs/policies/rate-limit/
  - https://kuma.io/docs/explore/gateway/
responseCodes:
  throttled: 429
  serviceUnavailable: 503
limits:
  - name: Control-plane REST API
    scope: deployment
    metric: varies
    limit: 'no vendor-imposed limit; bound by control-plane resource limits'
  - name: MeshRateLimit / RateLimit policy (data plane, user-configured)
    scope: dataplane
    metric: requests_per_second
    limit: 'user-defined per policy; default unset'
policies:
  - name: User-configured data-plane limits
    description: Operators define MeshRateLimit and RateLimit policies on the control plane; Envoy proxies
      enforce them at the data-plane edge between services and at gateways.
  - name: 429 response shape
    description: When a configured rate limit fires, Envoy returns HTTP 429 with optional Retry-After;
      gRPC traffic returns RESOURCE_EXHAUSTED.
  - name: Control-plane sizing
    description: Kuma scales horizontally; throughput on the REST API depends on the deployed control-plane
      replicas and the number of dataplanes connected.
  - name: Multi-zone replication
    description: In multi-zone deployments, policy synchronization between Global and Zone control planes
      uses xDS / KDS; rate of policy churn affects control-plane resource usage but is not numerically
      capped.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com