# Xử lý sự cố

> **TL;DR** — Bắt đầu từ triệu chứng, xem nguyên nhân trong bảng, và sửa ở phía bạn. Nếu vấn đề nằm ở phía Wandura, hoặc bạn không phân biệt được, hãy báo lên trong kênh Discord Wandura của team bạn kèm: **request id, thời điểm (UTC), endpoint, status, `error_code`, tổ chức**.

## Luồng xử lý
```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
```

## Triệu chứng
| Triệu chứng | Nguyên nhân thường gặp | Kiểm tra / cách sửa |
|---|---|---|
| Mọi lệnh gọi đều trả `401` | `WANDURA_API_KEY` rỗng hoặc sai; key đã bị thu hồi | In ra độ dài của key (41) và prefix; **Developers** hiện các key đã thu hồi. |
| `403` ở `/playback`, không có `error_code` | Key không có `playback` | Dùng một key **Stream films in an app**. |
| Thỉnh thoảng gặp `503` `service_unavailable` | Wandura không trả lời kịp | Bình thường: client của bạn sẽ retry. Không bao giờ xoay vòng key vì lỗi này. |
| Catalog `200` với `"films": []` | Tổ chức này chưa có giấy phép nào đang hoạt động (hoặc dùng nhầm key của tổ chức khác) | Hỏi Wandura phim nào được cấp phép, cho tổ chức nào. |
| Thiếu một phim đã được cấp phép | Nằm ngoài khung thời gian (UTC), chưa publish, hoặc giấy phép đã bị tắt | Hỏi Wandura ngày của giấy phép. |
| `not_ready` cho một tập từng có `stream_ready: true` | Đã bị rút hoặc thay thế kể từ lần đồng bộ trước | Đồng bộ lại; hiện "Chưa khả dụng". |
| `400` `invalid_device_info` | App gửi `(null)` hoặc một giá trị rỗng | Chỉ đọc giá trị thiết bị sau khi bước kiểm tra license của SDK đã qua. |
| `409` `sdk_required` | Không gửi giá trị thiết bị | Gửi `union_info` và `drm_kek`. |
| Player tải xong nhưng không bao giờ bắt đầu phát | Không phát qua Player SDK, hoặc bỏ sót một bước cài đặt | [Player SDK · lỗi thường gặp](https://docs.wandura.ai/vi/developers/player-sdk#common-problems). |
| Playback dừng sau khoảng 30 phút | Vé đã hết hạn | Xin một vé mới, phát tiếp ở đúng vị trí cũ. |
| `429` ở vé `play` | Một vòng lặp retry, xin vé cho cả bộ phim, hoặc một đỉnh lưu lượng thật | Kiểm tra ngân sách retry; nếu lưu lượng là thật, đề nghị nâng giới hạn. |
| Một lượt duyệt đồng bộ thấy một phim hai lần hoặc bỏ sót một phim | Catalog thay đổi giữa các trang | Là hành vi bình thường: loại trùng, áp dụng quy tắc hai lần vắng mặt ([Đồng bộ catalog](https://docs.wandura.ai/vi/developers/guides/catalog-sync)). |
| Creatives `422` `4222` | Cursor không hợp lệ (ví dụ lượt chạy bị khởi động lại giữa chừng) | Bắt đầu lại từ checkpoint của bạn. |
| Video mở trả `403` trên thiết bị | Link đã hết hạn, bị lưu trong app, hoặc bị sửa | Cấp link mới từ server của bạn; không bao giờ sửa URL. |
| `400` `unsupported_version` | Giá trị `Wandura-Version` sai, hoặc phiên bản của key bạn đã ngừng hỗ trợ | [Chuyển phiên bản](https://docs.wandura.ai/vi/developers/guides/migrating-versions). |

Mọi mã lỗi và ý nghĩa: [Lỗi](https://docs.wandura.ai/vi/developers/concepts/errors).

## Báo lên Wandura
Đăng trong kênh Discord Wandura của team bạn kèm:

| Trường | Ví dụ |
|---|---|
| Request id | `req_01J9Z3W2N8V4K7D5QX6T0B1C2M` (lấy từ header `Wandura-Request-Id` hoặc `request_id` trong body lỗi) |
| Thời điểm (UTC) | `2026-10-02T12:04:31Z` |
| Endpoint | `POST /api/delivery/v1/playback` |
| Status và `error_code` | `503` `service_unavailable` |
| Tổ chức | Tên tổ chức của bạn, và **prefix** của key |
| Với playback | Tập phim và `viewer_ref` bạn đã gửi |
| Bao nhiêu | Một người xem hay nhiều người? Từ khi nào? |

Không bao giờ dán key đầy đủ, `play_auth_token` hay link đã ký. Với key có thể đã bị lộ, hãy thu hồi key **trước**, rồi mới đăng ([Bảo mật](https://docs.wandura.ai/vi/developers/concepts/security#leaked-key)).

Trong giai đoạn beta không có SLA hay cam kết trực sự cố theo hợp đồng; Wandura trả lời trong kênh. Xem [Go-live · Hỗ trợ trong giai đoạn beta](https://docs.wandura.ai/vi/developers/production/go-live#support).

## Liên quan
- [Quan sát hệ thống](https://docs.wandura.ai/vi/developers/production/observability)
- [Câu hỏi thường gặp](https://docs.wandura.ai/vi/developers/help/faq)