Rate limits

The Delivery API applies an abuse ceiling per organisation. The ceiling is set far above the traffic of a normal integration, so reaching it usually means a runaway loop or a retry storm. This page explains how the ceiling is counted, what the API returns when you reach it and how to recover.

How requests are counted#

• Per organisation. Requests are counted for your organisation as a whole, not per key. Creating more keys does not raise your ceiling.
• Per endpoint group. Playback, the catalog and the creatives endpoints each have their own counter, so a runaway creatives sync cannot block your catalog.
• Fixed windows. Counts reset at the start of each window.
• Authenticated requests only. A request with a missing or invalid key is rejected before it is counted, so nobody else can use up your ceiling.

Every ticket request counts toward the playback ceiling, including requests with "intent": "prefetch".

Current limits#

Each window is one clock minute (UTC), so a count starts again at every whole minute. One viewer starting an episode usually costs about three playback tickets (the episode itself plus prefetches), so the playback limit is roughly 60 viewers starting an episode every second.

Wandura can raise any of these limits for your organisation alone: ask in your team's Wandura Discord channel. A raised limit takes effect within about a minute, with no change on your side. Wandura is also alerted when an organisation reaches its playback limit. On a 429, the X-RateLimit-Limit header shows the limit that applies to you.

When you reach the ceiling#

Every endpoint answers 429 Too Many Requests with a flat error body, including the creatives endpoints:

{
  "error": "Too many playback requests for this account. This is an abuse ceiling, not a quota — if a normal integration reaches it, contact us and it will be raised.",
  "error_code": "rate_limited"
}

The response carries these headers:

The limit headers appear only on 429 responses.

How to recover#

1. Stop sending requests to that endpoint group until Retry-After has passed. Retrying earlier only returns more 429s.
2. Look for the cause: a retry loop without backoff, a job that requests tickets for a whole catalog, or catalog calls made on every app launch instead of from a server-side cache.
3. If your normal traffic reaches the ceiling, ask in your team's Wandura Discord channel to have it raised.

Good habits#

• Cache the catalog on your server and refresh it on a schedule.
• Request playback tickets only when a viewer starts, or is about to start, an episode.
• Sync the creatives feed incrementally with updated_since.
• Use exponential backoff for 5xx responses.