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: Buf
providerId: buf
created: '2026-05-04'
modified: '2026-09-13'
generated: '2026-09-13'
method: searched
source: https://buf.build/docs/bsr/rate-limits/
docs: https://buf.build/docs/bsr/rate-limits/
supersedes: >-
  The 2026-05-04 bulk-sweep scaffold that previously occupied this file. Its tier quotas
  were placeholder values and have been replaced entirely by Buf's published limits.
description: >-
  Published rate limits for the public Buf Schema Registry at buf.build. Limits apply to
  ALL traffic regardless of plan; Pro (<org>.buf.dev) and Enterprise dedicated instances
  are not rate limited under current configuration, which is where Buf says high-volume
  production workloads usually run.
algorithm:
  model: GCRA leaky bucket
  parameters: [sustained rate, burst pool]
  bucket_selection: 'Each request lands in exactly one bucket, chosen by URL prefix.'
attribution:
  authenticated: 'per BSR user (valid Bearer token in Authorization)'
  unauthenticated: 'per source IP'
headers:
  limit: X-RateLimit-Limit
  remaining: X-RateLimit-Remaining
  reset: X-RateLimit-Reset
  retryAfter: Retry-After
header_semantics:
  X-RateLimit-Limit: Total requests allowed in the current window.
  X-RateLimit-Remaining: Requests still available before the bucket is empty.
  X-RateLimit-Reset: Seconds until the bucket fully refills.
  Retry-After: 'Set on rate-limited responses; seconds to wait before retrying.'
  always_present: true
exhaustion:
  http_status: 429
  connect_error_code: resource_exhausted
  remaining_header: 'X-RateLimit-Remaining: 0'
  retry_after: true
limit_count: 4
rate_limits:
  - id: general-api
    name: General API
    scope: per-user (authenticated) or per-IP (unauthenticated)
    limit: 30
    unit: requests
    window: second
    burst: 60
    applies_to: >-
      Most BSR calls — buf push, dependency resolution, module download (buf dep update,
      buf build against a remote module), plugin metadata queries. Shared across these
      endpoints; not a per-service limit.
    authenticated_tier: false
  - id: codegen-unauthenticated
    name: 'Code generation, unauthenticated'
    scope: per-IP
    limit: 10
    unit: requests
    window: hour
    burst: 10
    applies_to: 'CodeGenerationService.GenerateCode — what buf generate triggers with remote plugins.'
  - id: codegen-authenticated
    name: 'Code generation, authenticated'
    scope: per-user
    limit: 960
    unit: requests
    window: hour
    burst: 120
    applies_to: 'Same bucket, with a valid BSR token. Authenticating raises the limit roughly 100x.'
    note: >-
      One buf generate invocation counts as one request regardless of how many remote
      plugins it runs, up to a hard ceiling of 20 plugins per request; 22 remote plugins is
      rejected.
  - id: file-descriptor-set-service
    name: FileDescriptorSetService
    scope: per-user or per-IP
    limit: 1
    unit: requests
    window: second
    burst: 2
    applies_to: 'buf.reflect.v1beta1.FileDescriptorSetService'
    note: 'A carve-out from the General API bucket, not stacked on top of it.'
exemptions:
  - plan: Pro (dedicated instance, <org>.buf.dev)
    rate_limited: false
  - plan: Enterprise (dedicated instance)
    rate_limited: false
client_guidance:
  - 'Honor Retry-After; retrying earlier just produces another 429.'
  - 'Use exponentially increasing delays if the client does not surface Retry-After.'
  - 'In an interactive workflow, surface X-RateLimit-Reset to the user instead of silently retrying.'
raising_limits:
  - 'Authenticate — raises the code-generation bucket from 10/hour to 960/hour. The General API and FileDescriptorSetService buckets have no authenticated tier.'
  - 'Move production traffic to a Pro or Enterprise dedicated instance.'
  - 'Contact Buf for workloads that do not fit these patterns.'
caveat: 'Buf states these numbers reflect current policy and can change.'