Canonical API behaviour

TL;DR — This page is the contract. Every number and rule that more than one page relies on lives here once: authentication, pagination, ticket lifetime and reuse, how fresh each answer is, the retry policy, errors, rate limits and versioning. Other pages explain and link here; if two pages ever disagree, this page wins.

Authentication#

A bad Wandura-Version header is answered 400 before the key is even looked at. A key Wandura cannot check in time answers 503 service_unavailable: the key is fine, retry it. Key creation, rotation and revocation timings are on Security.

Pagination#

Three endpoints return pages. Each follows the same rules: the cursor is opaque (copy it, never build or decode it), and you stop when the next cursor is null, never because a page is short or empty.

Catalog pages are not one snapshot#

Each catalog page is cut from the catalog as it is at the moment that page is served. If Wandura publishes or withdraws a film, or a licence starts or ends, while you walk the pages, a film can be skipped or appear twice across pages. Sync safely:

1. If your catalog is a few hundred films or fewer, call GET /catalog without limit: one response is one consistent snapshot.
2. If you page, de-duplicate by film id (the later copy wins).
3. Apply withdrawals only after a complete walk: every page answered 200. A walk that failed part-way changes nothing.
4. Mark a film unavailable only when it was missing from two complete walks in a row. A film skipped once by a moving catalog comes back on the next walk.

The catalog sync guide implements exactly this.

The creatives feed has no such gap for unchanged records: it is ordered by update time then ID, so new updates land after the pages you have read. Records updated during your walk appear again on the next sync.

Playback tickets#

Lifetime#

A ticket is never extended, and once issued it cannot be recalled: it plays until expires_at even if the licence ends or the key is revoked a second later. GET /config gives both lifetimes for your key (playback.grant_ttl_seconds, playback.manifest_url_ttl_seconds).

One ticket per device#

A ticket is bound to the device values it was issued for (union_info and drm_kek). It decrypts only on that device. Never hand a ticket to another device, and never cache one under a key that does not include the device.

Reuse#

Reusing a ticket is allowed and encouraged, under these rules:

Views are counted from play requests. When a viewer starts an episode, always send a request with "intent": "play" for it, even if your app starts the player with a ticket it prefetched earlier. Prefetched tickets are not views.

Batches#

One request can ask for up to 3 tickets: episodes (1–3 items) or an anchor episode plus next (0–2). Each ticket counts 1 toward the playback limit. Each item has its own status; items are admitted one by one, prefetch items last. The whole request is 429 only when no item can be issued. Details: Request playback.

Freshness: how old an answer can be#

Wandura serves from short caches, so a change on Wandura's side reaches you after a bounded delay. These are the upper bounds.

• Several servers. Each Wandura server keeps its own cache, so two calls a few seconds apart can return slightly different snapshots. That is normal.
• During a Wandura database incident the catalog and licence checks are served from the last good answer for up to 5 minutes (stale-if-error), instead of failing. A change Wandura has already seen (a withdrawal, a suspension) is never undone by this.
• Tickets already issued are never recalled: they play until expires_at (≤ 30 minutes).

What to cache on your side, and for how long: Caching.

Retries#

The one retry policy for every Wandura call. The examples implement it.

Backoff. When Retry-After is present, wait that many seconds plus a random 0–1 s. Otherwise wait a random time between 0 and min(cap, base × 2^attempt) (full jitter).

Retry budget. Across a process, retries may be at most 10 % of the requests of the last minute (never fewer than 10 a minute). When the budget is spent, fail fast instead of adding load.

Concurrency. Walk pages one at a time, never in parallel. Retry only the failed items of a batch, each after its own retry_after. A retried ticket request with the same viewer_ref and device values usually returns the same ticket, so it does not count twice.

Errors#

• Two formats: a flat { "error", "error_code" } on catalog, playback, config and videos; an envelope { "code", "message", "server_time" } (no data) on creatives errors. Creatives 429 and 400 unsupported_version use the flat format.

• Branch on error_code (creatives: code). Unknown codes: decide by status class, as in the retry table above.

• Retry-After comes with 429 and with retryable 503s.

• Every response carries a Wandura-Request-Id header, and every JSON error body a request_id field. Quote it to support.

Every status and code, per endpoint, with what to do: Errors.

Rate limits#

Limits are per organisation (not per key), per counter, with the unit shown.

• Only requests with a valid key are counted.
• Counting is approximate on the high side by up to about 2.5 %.
• Close to the playback limit, prefetch tickets are refused first (429, "reason": "prefetch_shed", when less than about 20 % of the allowance is left), and a play request may be held up to 0.5 s instead of refused.
• GET /config reports your current limits for every counter except video.
• Wandura can raise any limit for your organisation on request.

How it behaves under load, and what to do: Rate limits.

Versioning#

Policy and deprecation headers: Versioning and API evolution.

Caching headers#

Every Delivery API response, tickets included, carries Cache-Control: no-store, and sets no cookies. Never store any of them in a shared cache (a CDN or a proxy): tickets, signed links and your catalog belong to your organisation only.

Related#

• API reference overview
• Errors
• Security