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: Twitch
providerId: twitch
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:
  - Streaming
  - Developer API
  - Rate Limiting
description: The Twitch Helix API protects services with a token-bucket algorithm. Each application receives
  separate buckets for app access tokens and user access tokens, and individual endpoints can charge non-default
  point values. User-token requests are scoped per client ID per user per minute. The Extensions API uses
  a separate rate-limit framework documented in the extensions guide.
sources:
  - https://dev.twitch.tv/docs/api/guide/
  - https://dev.twitch.tv/docs/api/
headers:
  limit: Ratelimit-Limit
  remaining: Ratelimit-Remaining
  reset: Ratelimit-Reset
responseCodes:
  throttled: 429
limits:
  - name: App Access Token Bucket
    scope: client-id (app token)
    metric: points_per_minute
    limit: 800
    timeFrame: minute
    notes: Default endpoint cost is 1 point per request; some endpoints charge more. A separate bucket
      per app access token applies.
  - name: User Access Token Bucket
    scope: client-id per user (user token)
    metric: points_per_minute
    limit: 800
    timeFrame: minute
    notes: Limits apply per client ID per user per minute when using user OAuth tokens.
  - name: Per-Endpoint Variable Cost
    scope: endpoint
    metric: points_per_request
    limit: see endpoint documentation
    notes: Some endpoints deduct more than 1 point per request; consult the specific endpoint reference
      for its point cost.
  - name: Extensions API
    scope: extension/client
    metric: varies
    limit: see Extensions API documentation
    notes: The Extensions API has its own rate-limit framework documented separately.
policies:
  - name: Token Bucket
    description: Each request deducts its endpoint's point value from the bucket; HTTP 429 is returned
      if the bucket would go below zero within the 1-minute window. The bucket replenishes at the documented
      rate.
  - name: Separate App vs User Buckets
    description: App access token requests and user access token requests draw from independent buckets;
      you do not need to choose between them, but you must track each separately.
  - name: Header-Driven Recovery
    description: Use Ratelimit-Remaining to back off proactively and Ratelimit-Reset (Unix timestamp)
      to wait the correct interval before retrying after a 429.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com