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: Storyblok
providerId: storyblok
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:
  - CMS
  - Content Delivery
  - Headless CMS
  - REST API
  - Rate Limiting
description: Storyblok publishes per-second rate limits on the Content Delivery API that vary by request
  type. Cached CDN requests get the highest ceiling (1,000 RPS); uncached single content entries and small
  listings allow 50 RPS, with limits scaling down as listing page size grows. Limits are per token/space.
  Beyond steady-state limits the API returns HTTP 429 and clients are expected to back off.
sources:
  - https://www.storyblok.com/docs/api/content-delivery/v2
responseCodes:
  throttled: 429
limits:
  - name: Cached CDN Requests
    scope: token
    metric: requests_per_second
    limit: 1000
    timeFrame: second
    notes: Cached responses served from the CDN.
  - name: Single Content Entry
    scope: token
    metric: requests_per_second
    limit: 50
    timeFrame: second
    notes: Single uncached content entry retrieval.
  - name: Listings up to 25 Entries
    scope: token
    metric: requests_per_second
    limit: 50
    timeFrame: second
    notes: List endpoints returning 25 or fewer entries per page.
  - name: Listings 25-50 Entries
    scope: token
    metric: requests_per_second
    limit: 15
    timeFrame: second
  - name: Listings 50-75 Entries
    scope: token
    metric: requests_per_second
    limit: 10
    timeFrame: second
  - name: Listings 75-100 Entries
    scope: token
    metric: requests_per_second
    limit: 6
    timeFrame: second
    notes: Per-second cap is reduced proportionally as page size increases beyond 25 entries.
policies:
  - name: Throttling Response
    description: When the rate limit is exceeded the API returns HTTP 429; clients should pause and retry
      with backoff.
  - name: Caching
    description: Storyblok recommends prioritizing cached requests, which have a 20x higher per-second
      ceiling than uncached single-entry requests.
  - name: Exponential Backoff
    description: Use exponential backoff with jitter on retry to avoid synchronized retry storms.
  - name: Plan Quotas
    description: Beyond per-second limits, monthly API request totals are bound by the subscribed plan
      (100k Starter, 1M Growth, 4M Growth Plus); overages above plan caps are billed at $10 per 1M extra
      requests.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com