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: PyPI
providerId: pypi
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:
  - Package Registry
  - Python
  - Open Source
  - Rate Limiting
description: PyPI does not publish a hard per-second rate limit. The JSON, Index, and RSS APIs are heavily
  cached and CDN-fronted via Fastly, so PyPI states there is "currently no rate limiting of PyPI APIs
  at the edge." The legacy XML-RPC API may be rate-limited if usage degrades service. PyPI reserves
  the right to ban irresponsible consumers.
notes: PyPI's rate-limit posture is a soft policy expressed in the docs.pypi.org help pages, not a numeric
  per-second table. Consumers must set a descriptive User-Agent that uniquely identifies their client.
sources:
  - https://docs.pypi.org/api/
headers:
  cache: X-Cache
  cacheHits: X-Cache-Hits
  etag: ETag
responseCodes:
  throttled: 429
limits:
  - name: JSON / Index / RSS APIs
    scope: IP
    metric: varies
    limit: 'no edge rate limit (heavily cached via Fastly CDN)'
    notes: 'PyPI states "currently no rate limiting of PyPI APIs at the edge"; consumers should still
      avoid thousands of requests per minute and should prefer ETag-conditional requests.'
  - name: XML-RPC API (legacy)
    scope: IP
    metric: varies
    limit: 'rate-limited at PyPI''s discretion if usage degrades service'
    notes: PyPI may temporarily or permanently throttle XML-RPC consumers whose usage causes service
      degradation.
policies:
  - name: User-Agent Identification
    description: Set a descriptive User-Agent that uniquely identifies your requests and ideally includes
      contact information; opaque or default agents may be rate-limited or blocked.
  - name: ETag and Conditional Requests
    description: The JSON, RSS, and Index APIs return ETag headers — use If-None-Match conditional
      requests to avoid hammering uncached origins.
  - name: Caching Awareness
    description: Inspect X-Cache and X-Cache-Hits to understand whether your requests are being served
      from CDN cache; design crawlers around the CDN rather than the origin.
  - name: Discretionary Bans
    description: PyPI reserves the right to temporarily or permanently prohibit a consumer based on
      irresponsible activity; sustained high-volume crawling without identification or backoff risks
      a block.
  - name: Pacing Guidance
    description: PyPI advises against thousands of requests in a short window (minutes); prefer serial
      requests over longer periods when feasible.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com