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: npm
providerId: npm
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:
  - Packages
  - JavaScript
  - Node.js
  - Package Management
  - Registry
  - Security
  - Rate Limiting
description: npm does not publish per-second or per-minute numeric rate limits for the public registry
  at registry.npmjs.org. Reads are anonymous and CDN-fronted; abusive traffic is throttled per-IP at the
  edge. The replication endpoint (replicate.npmjs.com) has explicit pagination caps. Authenticated publish
  and webhook operations are throttled at the application layer. Limits are not raised per tier; bulk
  consumers should use replication rather than scraping.
sources:
  - https://github.com/npm/registry/blob/main/docs/REGISTRY-API.md
  - https://github.com/orgs/community/discussions/152515
  - https://docs.npmjs.com/
responseCodes:
  throttled: 429
  serviceUnavailable: 503
limits:
  - name: Public registry reads
    scope: IP
    metric: varies
    limit: see CDN abuse policy; not numerically published
    applies:
      - npm Registry API
  - name: Replication _changes pagination
    scope: account
    metric: results_per_request
    limit: 10000
    notes: 'limit query parameter: default 1000, maximum 10000.'
    applies:
      - npm Registry API
  - name: Search API page size
    scope: IP
    metric: results_per_request
    limit: 250
    notes: size parameter on /-/v1/search; default 20, maximum 250.
    applies:
      - npm Registry API
  - name: Authenticated publish
    scope: account
    metric: varies
    limit: see registry abuse policy
    applies:
      - npm Registry API
      - npm CLI
policies:
  - name: Use replication for bulk
    description: For bulk indexing or mirroring, use /_changes and /_all_docs on replicate.npmjs.com with
      the npm-replication-opt-in header rather than scraping registry.npmjs.org.
  - name: Backoff
    description: Honor Retry-After when present; clients should implement exponential backoff with jitter
      on 429/503 responses.
  - name: Authentication for writes
    description: Publish, deprecate, and access-token operations require an npm token; reads are anonymous
      for public packages.
  - name: 2FA / Provenance
    description: Publishing requires 2FA on the account or a CI provenance attestation. Not a rate limit
      but governs which write requests are accepted.
maintainers:
  - FN: API Evangelist
    email: info@apievangelist.com