# Troubleshooting

> **TL;DR** — Start from the symptom, check the cause in the table, and fix it on your side. If the problem is on Wandura's side, or you cannot tell, escalate in your team's Wandura Discord channel with: **request id, time (UTC), endpoint, status, `error_code`, organisation**.

## The flow
```mermaid
flowchart TD
  A["Something fails"] --> B{"HTTP status?"}
  B -->|"401 / 403 without error_code"| K["Key or scope:<br/>check the key, its scopes, revocation"]
  B -->|"400 / 409 / 422"| R["Request: read error_code and fields,<br/>fix your code"]
  B -->|"403 not_entitled / 404 not_ready"| L["Licence or content:<br/>re-sync the catalog, check the film"]
  B -->|"429"| T["Your traffic:<br/>wait Retry-After, find the loop"]
  B -->|"5xx / timeout"| W{"Lasts more than 5 minutes,<br/>or many viewers?"}
  W -->|"No"| X["Retry policy handles it"]
  W -->|"Yes"| E["Escalate in your Discord channel"]
  K --> E2{"Still stuck?"}
  R --> E2
  L --> E2
  T --> E2
  E2 -->|"Yes"| E
```

## Symptoms
| Symptom | Likely cause | Check / fix |
|---|---|---|
| Every call answers `401` | Empty or wrong `WANDURA_API_KEY`; key revoked | Print the key's length (41) and prefix; **Developers** shows revoked keys. |
| `403` on `/playback`, no `error_code` | Key without `playback` | Use a **Stream films in an app** key. |
| `503` `service_unavailable` now and then | Wandura could not answer in time | Normal: retried by your client. Never rotate the key for it. |
| Catalog `200` with `"films": []` | No licence active for this organisation (or the wrong organisation's key) | Check with Wandura which films are licensed, to which organisation. |
| A licensed film is missing | Outside its window (UTC), not published, or licence switched off | Ask Wandura for the licence dates. |
| `not_ready` for an episode that was `stream_ready: true` | Withdrawn or replaced since your last sync | Re-sync; show "Not available yet". |
| `400` `invalid_device_info` | The app sent `(null)` or an empty value | Read device values only after the SDK licence check passed. |
| `409` `sdk_required` | No device values sent | Send `union_info` and `drm_kek`. |
| The player loads and never starts | Not playing through the Player SDK, or a missed setup step | [Player SDK · common problems](https://docs.wandura.ai/developers/player-sdk#common-problems). |
| Playback stops after about 30 minutes | Ticket expired | One fresh ticket, resume at the same position. |
| `429` on `play` tickets | A retry loop, tickets for a whole film, or a real peak | Check your retry budget; ask to raise the limit if traffic is real. |
| A sync walk sees a film twice or misses one | The catalog changed between pages | Expected: de-duplicate, two-miss rule ([Catalog sync](https://docs.wandura.ai/developers/guides/catalog-sync)). |
| Creatives `422` `4222` | Cursor invalid (for example the run restarted mid-way) | Restart from your checkpoint. |
| Open video `403` on the device | Link expired, stored in the app, or edited | Serve fresh links from your server; never edit the URL. |
| `400` `unsupported_version` | Bad `Wandura-Version` value, or your key's version was retired | [Migrating versions](https://docs.wandura.ai/developers/guides/migrating-versions). |

Every code and what it means: [Errors](https://docs.wandura.ai/developers/concepts/errors).

## Escalate
Post in your team's Wandura Discord channel with:

| Field | Example |
|---|---|
| Request id | `req_01J9Z3W2N8V4K7D5QX6T0B1C2M` (from the `Wandura-Request-Id` header or the error body's `request_id`) |
| Time (UTC) | `2026-10-02T12:04:31Z` |
| Endpoint | `POST /api/delivery/v1/playback` |
| Status and `error_code` | `503` `service_unavailable` |
| Organisation | Your organisation name, and the key **prefix** |
| For playback | The episode and the `viewer_ref` you sent |
| How many | One viewer, or many? Since when? |

Never paste a full key, a `play_auth_token` or a signed link. For a key that may have leaked, revoke it **first**, then post ([Security](https://docs.wandura.ai/developers/concepts/security#leaked-key)).

During the beta there is no contractual SLA or on-call commitment; Wandura answers in the channel. See [Go-live · Support during the beta](https://docs.wandura.ai/developers/production/go-live#support).

## Related
- [Observability](https://docs.wandura.ai/developers/production/observability)
- [FAQ](https://docs.wandura.ai/developers/help/faq)