Lịch sử thay đổi
Mọi lần sửa trang này, mới nhất ở trên. Mở từng mục để xem đã đổi gì.
- 04/10/2026 · +32 −0 dòng
Xem thay đổi
⋯ | 503 | `service_unavailable` | Wandura chưa đọc được catalog kịp lúc (`Could not read the catalog in time — retry`). | Sau `Retry-After` | — | Retry. **Không bao giờ** coi đây là catalog rỗng. | + ### Liệt kê bộ phim {#series-errors} + + `GET /api/delivery/v1/series` + + | Status | Mã | Khi nào | Retry? | Backend làm gì | + |---|---|---|---|---| + | 400 | `unsupported_version` (flat) | Phiên bản theo ngày không tồn tại hoặc đã ngừng. | Không | Gửi một phiên bản còn hỗ trợ. | + | 401 | `4010` | Không có header `Authorization: Bearer`. | Không | Sửa request. | + | 401 | `4011` | Key không tồn tại hoặc đã bị thu hồi. | Không | Kiểm tra key. | + | 403 | `4030` | Key thiếu `metadata:read`. | Không | Dùng key có scope đó. | + | 403 | `4031` | Tổ chức của bạn đang bị tạm ngưng. | Không | Liên hệ Wandura. | + | 422 | `4220` | `limit` không nằm trong 1–100, `updated_since` không phải giây epoch, hoặc `cursor` không phải giá trị endpoint này trả về. | Không | Sửa request; bắt đầu lại từ checkpoint gần nhất. | + | 429 | `rate_limited` (flat) | Đã chạm ngưỡng catalog (dùng chung với catalog). | Sau `Retry-After` | Chờ; đồng bộ thưa hơn. | + | 503 | `5030` | Danh sách tạm thời không khả dụng. | Backoff | Retry; giữ checkpoint. | + | 503 | `5031` | Wandura chưa kiểm được key kịp lúc. | Backoff | Retry. Đừng xoay key. | + + ### Lấy metadata một bộ phim {#series-get-errors} + + `GET /api/delivery/v1/series/{code}` + + | Status | Mã | Khi nào | Retry? | Backend làm gì | + |---|---|---|---|---| + | 400 | `unsupported_version` (flat) | Phiên bản theo ngày không tồn tại hoặc đã ngừng. | Không | Gửi một phiên bản còn hỗ trợ. | + | 401 | `4010` | Không có header `Authorization: Bearer`. | Không | Sửa request. | + | 401 | `4011` | Key không tồn tại hoặc đã bị thu hồi. | Không | Kiểm tra key. | + | 403 | `4030` | Key thiếu `metadata:read`. | Không | Dùng key có scope đó. | + | 403 | `4031` | Tổ chức của bạn đang bị tạm ngưng. | Không | Liên hệ Wandura. | + | 404 | `4040` | Không có bộ này, hoặc tổ chức của bạn không được stream nó (cố ý trả cùng một câu). | Không | Ngừng hiển thị bộ đó; xem lại danh sách. | + | 429 | `rate_limited` (flat) | Đã chạm ngưỡng catalog (dùng chung với catalog). | Sau `Retry-After` | Chờ. | + | 503 | `5030` | Bộ phim tạm thời không khả dụng. | Backoff | Retry. | + | 503 | `5031` | Wandura chưa kiểm được key kịp lúc. | Backoff | Retry. | + ### Playback {#playback-errors} ⋯
- 02/10/2026 · +2 −2 dòng
Xem thay đổi
⋯ ### Request id {#request-id} - > **Đang triển khai.** Mọi response mang header `Wandura-Request-Id` (ví dụ `req_01J9Z3W2N8V4K7D5QX6T0B1C2M`), và mọi body lỗi, phẳng hay envelope, có trường `request_id` cùng giá trị. Hãy ghi log giá trị này, và trích dẫn khi liên hệ hỗ trợ: nó giúp tìm đúng request trong log của Wandura. + Mọi response mang header `Wandura-Request-Id` (ví dụ `req_01J9Z3W2N8V4K7D5QX6T0B1C2M`), và mọi body lỗi JSON, phẳng hay envelope, có trường `request_id` cùng giá trị. Hãy ghi log giá trị này, và trích dẫn khi liên hệ hỗ trợ: nó giúp tìm đúng request trong log của Wandura. Trong lúc tính năng này chưa chạy, hãy gửi kèm endpoint, thời điểm theo UTC chính xác tới giây, status, mã lỗi và tiền tố key của bạn. ⋯ > **Đừng làm việc không đảo ngược được chỉ vì một câu trả lời.** Trước khi ngừng bán phim hoặc hoàn tiền cho người xem vì `not_entitled` hay `not_ready`, hãy xác nhận bằng lần đồng bộ catalog kế tiếp: phim bị rút sẽ biến mất khỏi catalog. - > **Đang triển khai.** Nếu trong lúc cấp vé Wandura chưa kiểm được giấy phép hoặc tập kịp lúc, Wandura trả `503` `service_unavailable` (`Could not check the licence or episode right now — retry`) kèm `Retry-After`, không bao giờ trả `404` hay `403`. Cứ tiếp tục bán, và retry. + Nếu trong lúc cấp vé Wandura chưa kiểm được giấy phép hoặc tập kịp lúc, Wandura trả `503` `service_unavailable` (`Could not check the licence or episode right now — retry`) kèm `Retry-After`, không bao giờ trả `404` hay `403`. Cứ tiếp tục bán, và retry. #### Các `reason` của `not_entitled` {#not-entitled-reasons} ⋯
- 02/10/2026 · +181 −73 dòng
Xem thay đổi
# Lỗi - Delivery API dùng HTTP status code chuẩn và bổ sung một mã máy đọc được cho hầu hết các lỗi. Endpoint catalog và playback trả về một object lỗi phẳng với chuỗi `error_code`; endpoint creatives trả về một envelope với `code` dạng số. Trang này liệt kê mọi lỗi mà từng endpoint trả về hiện nay, ý nghĩa của lỗi và cách xử lý. + > **TL;DR** — Rẽ nhánh theo `error_code` (với creatives: `code` dạng số), không bao giờ theo thông điệp. Luôn có nhánh mặc định: mã lạ được xử lý theo nhóm HTTP status (`429` và `5xx` thì retry, các `4xx` khác thì không). Trang này liệt kê mọi status và mã mà từng endpoint trả về, kèm việc app hiển thị gì và backend làm gì. Khi nào retry và retry thế nào: [chính sách retry](../reference/behaviour.md#retries). - ## Định dạng lỗi + ## Định dạng lỗi {#error-formats} - ### Catalog và playback + ### Định dạng phẳng {#flat-format} + Catalog, playback, cấu hình và video mở dùng một object phẳng: + ```json { ⋯ | Trường | Kiểu | Mô tả | |---|---|---| - | `error` | string | Thông điệp cho người đọc. Hãy ghi log, nhưng đừng parse, trừ `403` của catalog bên dưới. | - | `error_code` | string | Mã máy đọc được. Rẽ nhánh theo trường này. Một số lỗi không có trường này, bảng bên dưới ghi là "không có". | - | `reason` | string | Chỉ có với `not_entitled`: lý do chi tiết, dùng cho log và hỗ trợ. | - | `fields` | mảng string | Chỉ có với `invalid_device_info`: các giá trị thiết bị bị từ chối. | - | `protection` | string | Chỉ có với `sdk_required`: mức bảo vệ của tập. | + | `error` | string | Thông điệp để ghi log. Đừng hiển thị cho người xem và đừng parse, trừ những dòng bên dưới ghi rằng mã nằm trong `error`. | + | `error_code` | string | Mã máy đọc được. Rẽ nhánh theo trường này. Một số lỗi không có trường này (bảng bên dưới ghi là **không có**). | + | `reason` | string | Với `not_entitled`, và với `429` `prefetch_shed`: lý do chi tiết. | + | `fields` | mảng string | Với `invalid_device_info`: các giá trị thiết bị bị từ chối. | + | `protection` | string | Với `sdk_required`: mức bảo vệ của tập. | + | `supported_versions`, `latest_version`, `upgrade_to` | | Với `unsupported_version`: những gì bạn có thể gửi thay thế. | - ### Creative + Một vài response `4xx` không có `error_code` mà đặt một mã ổn định trong `error`: `org_suspended`, `app_not_registered`, `collection_not_found` và `video_not_found`. Hãy so sánh nguyên chuỗi. + ### Envelope của creatives {#creatives-envelope} + + Các endpoint creatives bọc lỗi trong một envelope với `code` dạng số. Lỗi **không có** trường `data`: + ```json { ⋯ ``` - | Trường | Kiểu | Mô tả | - |---|---|---| - | `code` | integer | `0` khi thành công, mã lỗi bốn chữ số trong trường hợp khác. Ba chữ số đầu là HTTP status. | - | `message` | string | Thông điệp cho người đọc. Đừng parse. | - | `server_time` | integer | Giờ server tính bằng giây Unix epoch. | + `code` có bốn chữ số: ba chữ số đầu là HTTP status. Hai response của creatives dùng định dạng **phẳng** thay vì envelope: `429` `rate_limited` và `400` `unsupported_version`. - Ngoại lệ duy nhất là `429`: endpoint creatives trả lỗi này ở định dạng phẳng, với `error_code` `rate_limited`. Xem [Rate limit](rate-limits.md). + ### Request id {#request-id} - ## Xử lý lỗi theo mã + > **Đang triển khai.** Mọi response mang header `Wandura-Request-Id` (ví dụ `req_01J9Z3W2N8V4K7D5QX6T0B1C2M`), và mọi body lỗi, phẳng hay envelope, có trường `request_id` cùng giá trị. Hãy ghi log giá trị này, và trích dẫn khi liên hệ hỗ trợ: nó giúp tìm đúng request trong log của Wandura. - - Rẽ nhánh theo `error_code` (hoặc `code` với creatives), không chỉ dựa vào HTTP status. Nhiều tình huống khác nhau dùng chung một status. - - Luôn có nhánh mặc định. Wandura có thể thêm mã mới trong `v1`, và app không có nhánh mặc định sẽ hiện màn hình trắng khi gặp mã mới. - - Không bao giờ hiển thị văn bản `error` hay `message` cho người xem. Hãy ánh xạ mã sang nội dung của riêng bạn. + Trong lúc tính năng này chưa chạy, hãy gửi kèm endpoint, thời điểm theo UTC chính xác tới giây, status, mã lỗi và tiền tố key của bạn. - ## Lỗi catalog {#catalog-errors} + ## Xử lý lỗi theo mã {#handle-by-code} - `GET /api/delivery/v1/catalog` + | Bạn nhận được | Làm gì | + |---|---| + | Một mã có trong trang này | Làm theo dòng của mã đó. | + | Một `error_code` lạ với `429` | Chờ hết `Retry-After`, rồi retry. | + | Một `error_code` lạ với một `4xx` khác | Không retry. Hiển thị lỗi chung và báo cho kỹ sư của bạn. | + | Một `error_code` lạ với `5xx` | Retry với backoff, như `503`. | + | Không có body, hoặc body không phải JSON | Quyết định theo nhóm status, cùng cách như trên. | - | Status | `error_code` | Thông điệp | Ý nghĩa | Cách xử lý | + Mã mới có thể xuất hiện trong `v1` bất cứ lúc nào; app không có nhánh mặc định sẽ hiện màn hình trắng khi gặp mã mới. Không bao giờ hiển thị `error` hay `message` cho người xem: hãy ánh xạ mã sang nội dung của riêng bạn. + + ### `Retry-After` {#retry-after} + + Được gửi kèm mọi `429`, và các `503` được ghi "Sau `Retry-After`" bên dưới. Không bao giờ retry sớm hơn. `503` `not_ready`, các `503` của creatives, `502` và `500` không có header này: hãy dùng backoff. + + ## Thông báo cho người xem {#viewer-messages} + + Cột "App hiển thị" bên dưới dùng bốn thông báo này. Hãy dùng câu chữ của riêng bạn. + + | Thông báo | Khi nào | + |---|---| + | **Không khả dụng** — "Phim này không còn khả dụng" | Giấy phép không hoạt động. | + | **Chưa có** — "Chưa khả dụng" | Lúc này tập chưa phát được. | + | **Bận** — "Hệ thống đang bận, thử lại sau giây lát" | Đã retry mà vẫn lỗi tạm thời. | + | **Hỏng** — "Không tải được tập này" | Lỗi trong tích hợp của bạn. Báo cho kỹ sư của bạn. | + + ## Mọi endpoint {#all-endpoints} + + ### Mọi path {#every-path} + + | Status | Mã | Khi nào | Retry? | Làm gì | |---|---|---|---|---| - | 401 | không có | `Missing Bearer API key` | Không có header `Authorization: Bearer`. | Sửa request. Không retry. | - | 401 | không có | `Invalid or revoked API key` | Key không tồn tại hoặc đã bị thu hồi. | Kiểm tra key. Không retry. | - | 403 | không có | `This API key does not have the metadata:read scope` | Key thiếu scope. | Dùng key có `metadata:read`. | - | 403 | không có | `org_suspended` | Quyền truy cập của tổ chức bạn đang bị tạm ngưng. | Liên hệ Wandura. Không retry. | - | 429 | `rate_limited` | | Đã chạm rate limit. | Chờ hết `Retry-After`. | - | 503 | `service_unavailable` | `Could not verify the API key right now — retry` | Wandura chưa kiểm được key kịp lúc. Key **không** sai. | Chờ đúng `Retry-After` giây rồi thử lại, có backoff. Đừng xoay key. | + | 404 | `not_found` | Path lạ dưới `/api/delivery/v1/`, với bất kỳ method nào. Không có header `Wandura-Version`. | Không | Sửa path. | + | 405 | không có (empty body) | Path có thật nhưng sai method, ví dụ `GET /playback`. Header `Allow` liệt kê method đúng. | Không | Sửa method. | - ## Lỗi playback {#playback-errors} + ### Catalog {#catalog-errors} - `POST /api/delivery/v1/playback` + `GET /api/delivery/v1/catalog` - | Status | `error_code` | Ý nghĩa | Cách xử lý | - |---|---|---|---| - | 400 | không có | Body không phải JSON hợp lệ, hoặc không có `episode_id` cũng không có `film_ref` kèm `episode_no` dạng số. | Sửa request. | - | 400 | `invalid_request` | Chỉ gửi một trong hai `union_info` và `drm_kek`. | Gửi cả hai. | - | 400 | `invalid_device_info` | Một giá trị thiết bị trông như rỗng hoặc không hợp lệ, ví dụ chuỗi `"(null)"`. `fields` nêu các giá trị sai. | Sửa cách app đọc giá trị từ Player SDK. | - | 401 | không có | API key bị thiếu, không hợp lệ hoặc đã bị thu hồi. | Kiểm tra key. Không retry. | - | 403 | không có | Key thiếu scope `playback`. | Dùng một playback key: tạo trên **Developers** → **Stream films in an app**. | - | 403 | `not_entitled` | Tổ chức của bạn hiện không được cấp phép stream phim này. `reason` cho biết chi tiết. | Hiển thị trạng thái khoá hoặc không khả dụng. Không retry. | - | 404 | `not_ready` | Tập hoặc phim không tồn tại, chưa publish, hoặc chưa sẵn sàng để stream. | Hiển thị "chưa khả dụng". Làm mới catalog. | - | 409 | `sdk_required` | Tập đã mã hoá và request không có giá trị thiết bị. | Gửi lại kèm `union_info` và `drm_kek`. | - | 429 | `rate_limited` | Đã chạm rate limit. | Chờ hết `Retry-After`. | - | 502 | không có | Wandura không chuẩn bị được stream hoặc không ký được play token. | Retry với backoff. | - | 503 | `not_ready` | Hiện chưa có phiên bản phát được của tập này. | Hiển thị "chưa khả dụng". Thử lại sau. | - | 503 | `service_unavailable` | Wandura chưa kiểm được API key kịp lúc. Key **không** sai. | Chờ đúng `Retry-After` giây rồi thử lại, có backoff. Đừng xoay key. | - | 503 | `service_unavailable` | Nhà cung cấp video chưa trả lời kịp (chỉ ở playback). Tập phim và key đều không có vấn đề. | Chờ đúng `Retry-After` giây (2) rồi thử lại, có backoff. | + | Status | Mã | Khi nào | Retry? | App hiển thị | Backend làm gì | + |---|---|---|---|---|---| + | 400 | `invalid_request` | `limit` không nằm trong 1–200, hoặc `cursor` bị sửa. | Không | — | Sửa request. Đi lại từ trang đầu. | + | 400 | `unsupported_version` | Header `Wandura-Version`, hoặc phiên bản key của bạn đang ghim, không tồn tại hoặc đã ngừng. | Không | — | Gửi một phiên bản còn hỗ trợ; xem [Chuyển phiên bản](../guides/migrating-versions.md). | + | 401 | không có | Thiếu header, hoặc key không tồn tại hay đã bị thu hồi. | Không | — | Kiểm tra key. Giữ catalog cũ của bạn. | + | 403 | không có | Key thiếu `metadata:read`. | Không | — | Dùng key có scope đó. | + | 403 | `org_suspended` (in `error`) | Tổ chức của bạn đang bị tạm ngưng. | Không | — | Giữ bản sao, ngừng bán, liên hệ Wandura. | + | 429 | `rate_limited` | Đã chạm ngưỡng catalog. | Sau `Retry-After` | — | Chờ, rồi tìm vòng lặp gây ra. | + | 503 | `service_unavailable` | Wandura chưa kiểm được key kịp lúc. Key không sai. | Sau `Retry-After` | — | Retry. Không bao giờ xoay key vì lỗi này. | + | 503 | `service_unavailable` | Wandura chưa đọc được catalog kịp lúc (`Could not read the catalog in time — retry`). | Sau `Retry-After` | — | Retry. **Không bao giờ** coi đây là catalog rỗng. | - ### Các `reason` của `not_entitled` + ### Playback {#playback-errors} - Với `not_entitled`, trường `reason` cho biết lý do. Hãy ghi log và trích dẫn nó khi liên hệ hỗ trợ, nhưng đừng dựng màn hình riêng cho từng lý do: tất cả đều có nghĩa là "hiện không được cấp phép", và có thể có lý do mới được thêm vào. + `POST /api/delivery/v1/playback`. Trong một lô, các dòng cấp request trả lời cho cả request; các dòng cấp vé nằm trong `items[]`, mỗi phần tử có `status` riêng (và `retry_after` thay cho header). + **Cả request** + + | Status | Mã | Khi nào | Retry? | App hiển thị | Backend làm gì | + |---|---|---|---|---|---| + | 400 | không có | Body không phải JSON, hoặc không có `episode_id` cũng không có `film_ref` kèm `episode_no` dạng số. | Không | Hỏng | Sửa request. | + | 400 | `invalid_request` | Chỉ có một trong hai `union_info` và `drm_kek`, hoặc lô sai định dạng. | Không | Hỏng | Sửa request. | + | 400 | `invalid_device_info` | Một giá trị thiết bị trông như rỗng, ví dụ `"(null)"`, hoặc ngắn hơn 8 ký tự. `fields` nêu tên giá trị đó. | Không | Hỏng | Sửa cách app đọc giá trị từ Player SDK. Báo động. | + | 400 | `unsupported_version` | Phiên bản theo ngày không tồn tại hoặc đã ngừng. | Không | Hỏng | Xem [Chuyển phiên bản](../guides/migrating-versions.md). | + | 401 | không có | Thiếu header, hoặc key không tồn tại hay đã bị thu hồi. | Không | Hỏng | Kiểm tra key. Báo động. | + | 403 | không có | Key thiếu `playback`. | Không | Hỏng | Dùng một playback key. | + | 429 | `rate_limited` | Đã chạm ngưỡng playback với mọi phần tử. Kèm `"reason": "prefetch_shed"`: prefetch đang tạm dừng vì gần chạm ngưỡng. | Sau `Retry-After` | Bận (play); không hiện gì (prefetch) | Retry các lượt play; bỏ các prefetch. Xem [Rate limit](rate-limits.md). | + | 503 | `service_unavailable` | Wandura chưa kiểm được key kịp lúc. | Sau `Retry-After` | Bận | Retry. Đừng xoay key. | + | 500 | không có (rare) | Lỗi không lường trước. | Backoff | Bận | Retry một lần; báo lại kèm thời điểm. | + + **Từng vé** (ở cấp ngoài cùng khi xin một tập, hoặc một phần tử của lô) + + | Status | Mã | Khi nào | Retry? | App hiển thị | Backend làm gì | + |---|---|---|---|---|---| + | 403 | `not_entitled` | Lúc này tổ chức của bạn không được stream phim này. `reason` cho biết lý do (bảng bên dưới). | Không | Không khả dụng | Ghi log `reason`. Ngừng bán phim khi lần đồng bộ catalog kế tiếp xác nhận phim đã không còn. | + | 404 | `not_ready` | Tập hoặc phim không tồn tại, chưa publish hoặc chưa sẵn sàng. | Không | Chưa có | Làm mới catalog. | + | 409 | `sdk_required` | Tập đã mã hoá mà không có giá trị thiết bị. | Không | Hỏng | Gửi `union_info` và `drm_kek`. Báo động. | + | 429 | `rate_limited` | Phần tử này không được nhận (chỉ trong lô). `reason` `prefetch_shed` với prefetch bị tạm dừng. | Sau `retry_after` | Không hiện gì với prefetch | Chỉ retry phần tử này. | + | 502 | không có | Không chuẩn bị được stream, hoặc không ký được play token. | Backoff | Bận | Retry, rồi báo lại. | + | 503 | `not_ready` | Lúc này chưa có phiên bản phát được của tập. Không có `Retry-After`. | Không phải bây giờ | Chưa có | Thử lại sau (lượt phát hoặc lần đồng bộ kế tiếp). | + | 503 | `service_unavailable` | Nhà cung cấp video chưa trả lời kịp (`The video provider did not answer in time — retry`). | Sau `Retry-After` (2 giây) | Bận | Retry. Tập phim không hề bị thiếu. | + | 503 | `service_unavailable` | Lúc này chưa cấp được vé (`Could not issue this grant right now — retry`). | Sau `Retry-After` | Bận | Retry. | + + > **Đừng làm việc không đảo ngược được chỉ vì một câu trả lời.** Trước khi ngừng bán phim hoặc hoàn tiền cho người xem vì `not_entitled` hay `not_ready`, hãy xác nhận bằng lần đồng bộ catalog kế tiếp: phim bị rút sẽ biến mất khỏi catalog. + + > **Đang triển khai.** Nếu trong lúc cấp vé Wandura chưa kiểm được giấy phép hoặc tập kịp lúc, Wandura trả `503` `service_unavailable` (`Could not check the licence or episode right now — retry`) kèm `Retry-After`, không bao giờ trả `404` hay `403`. Cứ tiếp tục bán, và retry. + + #### Các `reason` của `not_entitled` {#not-entitled-reasons} + + Ghi log `reason` và trích dẫn khi liên hệ hỗ trợ, nhưng hiển thị cùng một màn hình cho mọi lý do: có thể có lý do mới được thêm vào. + | `reason` | Ý nghĩa | |---|---| ⋯ | `entitlement_not_found` | Tổ chức của bạn không có giấy phép cho phim này. | | `entitlement_suspended` | Giấy phép của bạn cho phim này đang bị tạm ngưng. | - | `streaming_disabled` | Giấy phép của bạn cho phim này không bao gồm quyền streaming. | - | `outside_window` | Hôm nay nằm ngoài khung thời gian giấy phép của bạn cho phim này. | + | `streaming_disabled` | Giấy phép của bạn cho phim này không gồm quyền streaming. | + | `outside_window` | Hôm nay (UTC) nằm ngoài khung thời gian của giấy phép. | - ## Lỗi creative {#creatives-errors} + ### Cấu hình {#config-errors} - `GET /api/delivery/v1/creatives` và `GET /api/delivery/v1/creatives/{id}` + `GET /api/delivery/v1/config` - | Status | `code` | Thông điệp | Ý nghĩa | Cách xử lý | + | Status | Mã | Khi nào | Retry? | Backend làm gì | |---|---|---|---|---| - | 401 | 4010 | `Missing Bearer API key` | Không có header `Authorization: Bearer`. | Sửa request. | - | 401 | 4011 | `Invalid or revoked API key` | Key không tồn tại hoặc đã bị thu hồi. | Kiểm tra key. Không retry. | - | 403 | 4030 | `This API key does not have the creatives:export scope` | Key thiếu scope. | Dùng key có `creatives:export`. | - | 403 | 4031 | `org_suspended` | Quyền truy cập của tổ chức bạn đang bị tạm ngưng. | Liên hệ Wandura. | - | 404 | 4040 | `Creative not found` | Chỉ với `GET /creatives/{id}`. Creative không tồn tại, thuộc tổ chức khác hoặc chưa được duyệt. | Gỡ nó khỏi tập creative đang dùng. | - | 422 | 4220 | `limit must be an integer between 1 and 100` | Chỉ với endpoint liệt kê. `limit` sai. | Sửa request. | - | 422 | 4221 | `updated_since must be epoch seconds` | Chỉ với endpoint liệt kê. `updated_since` sai. | Sửa request. | - | 422 | 4222 | `cursor is not valid` | Chỉ với endpoint liệt kê. Cursor đã bị sửa hoặc bị cắt ngắn. | Bắt đầu lại từ checkpoint gần nhất. | - | 429 | không có (body phẳng, `error_code` `rate_limited`) | | Đã chạm rate limit. | Chờ hết `Retry-After`. | - | 503 | 5030 | `The creative feed is temporarily unavailable` | Sự cố tạm thời phía Wandura. | Retry với backoff. | - | 503 | 5031 | `Could not verify the API key right now — retry` | Wandura chưa kiểm được key kịp lúc. Key **không** sai. | Retry với backoff. Đừng xoay key. | + | 400 | `unsupported_version` | Phiên bản theo ngày không tồn tại hoặc đã ngừng. | Không | Gửi một phiên bản còn hỗ trợ. | + | 401 | không có | Thiếu header, hoặc key không tồn tại hay đã bị thu hồi. | Không | Kiểm tra key. | + | 403 | `org_suspended` (in `error`) | Tổ chức của bạn đang bị tạm ngưng. | Không | Liên hệ Wandura. | + | 429 | `rate_limited` | Đã chạm ngưỡng cấu hình. | Sau `Retry-After` | Đọc thưa hơn: lúc khởi động hoặc vài giờ một lần. | + | 503 | `service_unavailable` | Wandura chưa kiểm được key kịp lúc. | Sau `Retry-After` | Retry; giữ cấu hình đang có. | + | 503 | `service_unavailable` | Wandura chưa đọc được cấu hình của bạn kịp lúc (`Could not read your configuration in time — retry`). | Sau `Retry-After` | Retry; giữ cấu hình đang có. | - ## Hướng dẫn retry + ### Liệt kê creative {#creatives-errors} - | Tình huống | Retry? | - |---|---| - | `400`, `401`, `403`, `409`, `422` | Không. Hãy sửa request, key hoặc giấy phép trước. | - | `404` / `not_ready` | Không retry ngay. Làm mới catalog và thử lại sau. | - | `429` | Có, sau số giây ghi trong `Retry-After`. | - | `502`, `503`, các `5xx` khác | Có, với exponential backoff và giới hạn số lần, ví dụ 1 s, 2 s, 4 s, rồi dừng. | + `GET /api/delivery/v1/creatives` - Trong lúc phát, xin vé mới một lần khi Player SDK lỗi, sau đó làm theo bảng này. Xem [Playback](playback.md#expiry). Jitter, ngân sách retry và code mẫu: xem [Phát mượt khi tải cao](../guides/smooth-playback.md#retry). + | Status | Mã | Khi nào | Retry? | Backend làm gì | + |---|---|---|---|---| + | 400 | `unsupported_version` (flat) | Phiên bản theo ngày không tồn tại hoặc đã ngừng. | Không | Gửi một phiên bản còn hỗ trợ. | + | 401 | `4010` | Không có header `Authorization: Bearer`. | Không | Sửa request. | + | 401 | `4011` | Key không tồn tại hoặc đã bị thu hồi. | Không | Kiểm tra key. | + | 403 | `4030` | Key thiếu `creatives:export`. | Không | Dùng key có scope đó. | + | 403 | `4031` | Tổ chức của bạn đang bị tạm ngưng. | Không | Liên hệ Wandura. | + | 422 | `4220` | `limit` không nằm trong 1–100 (`limit=` rỗng được tính là 0). | Không | Sửa request. | + | 422 | `4221` | `updated_since` không phải giây epoch. | Không | Sửa request. | + | 422 | `4222` | `cursor` không hợp lệ. | Không | Bắt đầu lại từ checkpoint gần nhất. | + | 429 | `rate_limited` (flat) | Đã chạm ngưỡng creatives. | Sau `Retry-After` | Chờ; đồng bộ thưa hơn. | + | 503 | `5030` | Feed tạm thời không khả dụng. | Backoff | Retry; giữ checkpoint. | + | 503 | `5031` | Wandura chưa kiểm được key kịp lúc. | Backoff | Retry. Đừng xoay key. | - ## Nhận trợ giúp + ### Lấy một creative {#creative-get-errors} - Nếu lỗi vẫn tiếp diễn, hãy liên hệ hỗ trợ kèm các thông tin liệt kê trong [Hỗ trợ](../help/support.md). + `GET /api/delivery/v1/creatives/{id}` + + | Status | Mã | Khi nào | Retry? | Backend làm gì | + |---|---|---|---|---| + | 400 | `unsupported_version` (flat) | Phiên bản theo ngày không tồn tại hoặc đã ngừng. | Không | Gửi một phiên bản còn hỗ trợ. | + | 401 | `4010` | Không có header `Authorization: Bearer`. | Không | Sửa request. | + | 401 | `4011` | Key không tồn tại hoặc đã bị thu hồi. | Không | Kiểm tra key. | + | 403 | `4030` | Key thiếu `creatives:export`. | Không | Dùng key có scope đó. | + | 403 | `4031` | Tổ chức của bạn đang bị tạm ngưng. | Không | Liên hệ Wandura. | + | 404 | `4040` | Không có creative đã duyệt nào với ID này cho tổ chức của bạn (cũng vậy khi ID không phải UUID). | Không | Gỡ nó khỏi tập đang dùng của bạn. | + | 429 | `rate_limited` (flat) | Đã chạm ngưỡng creatives (dùng chung với endpoint danh sách). | Sau `Retry-After` | Chờ. | + | 503 | `5030` | Feed tạm thời không khả dụng. | Backoff | Retry. | + | 503 | `5031` | Wandura chưa kiểm được key kịp lúc. | Backoff | Retry. | + + ### Liệt kê video mở {#videos-errors} + + `GET /api/delivery/v1/videos` + + | Status | Mã | Khi nào | Retry? | Backend làm gì | + |---|---|---|---|---| + | 400 | không có | `cursor` không phải token do endpoint này cấp, hoặc `limit` không nằm trong 1–200. | Không | Sửa request; quét lại từ đầu. | + | 400 | `unsupported_version` | Phiên bản theo ngày không tồn tại hoặc đã ngừng. | Không | Gửi một phiên bản còn hỗ trợ. | + | 401 | không có | Thiếu header, hoặc key không tồn tại hay đã bị thu hồi. | Không | Kiểm tra key. | + | 403 | không có | Key thiếu `videos:read`. | Không | Dùng key video mở của app. | + | 403 | `app_not_registered` (in `error`) | Key không gắn với app nào. | Không | Đăng ký app; dùng key của app đó. | + | 403 | `org_suspended` (in `error`) | Tổ chức của bạn đang bị tạm ngưng. | Không | Liên hệ Wandura. | + | 404 | `collection_not_found` (in `error`) | Không tồn tại, chưa publish hoặc không được cấp cho bạn. | Không | Kiểm tra mã bộ sưu tập. | + | 429 | `rate_limited` | Đã chạm ngưỡng danh sách. | Sau `Retry-After` | Chờ; cache danh sách. | + | 500 | không có | Không đọc được danh sách. | Backoff | Retry; tiếp tục phục vụ danh sách cũ. | + | 503 | `service_unavailable` | Wandura chưa kiểm được key kịp lúc. | Sau `Retry-After` | Retry. | + + ### Lấy một video mở {#video-errors} + + `GET /api/delivery/v1/videos/{id}` + + | Status | Mã | Khi nào | Retry? | Backend làm gì | + |---|---|---|---|---| + | 400 | không có | `id` không phải UUID. | Không | Dùng `id` lấy từ danh sách. | + | 400 | `unsupported_version` | Phiên bản theo ngày không tồn tại hoặc đã ngừng. | Không | Gửi một phiên bản còn hỗ trợ. | + | 401 | không có | Thiếu header, hoặc key không tồn tại hay đã bị thu hồi. | Không | Kiểm tra key. | + | 403 | không có | Key thiếu `videos:read`. | Không | Dùng key video mở của app. | + | 403 | `app_not_registered` (in `error`) | Key không gắn với app nào. | Không | Đăng ký app. | + | 403 | `org_suspended` (in `error`) | Tổ chức của bạn đang bị tạm ngưng. | Không | Liên hệ Wandura. | + | 404 | `video_not_found` (in `error`) | Không tồn tại, không được cấp, chưa publish, đã lưu trữ hoặc chưa phát được. | Không | Bỏ nó khỏi danh sách của bạn. | + | 429 | `rate_limited` | Đã chạm ngưỡng một video (bộ đếm riêng). | Sau `Retry-After` | Chờ; ưu tiên dùng danh sách đã cache. | + | 500 | không có | Không đọc được video. | Backoff | Retry. | + | 503 | `service_unavailable` | Wandura chưa kiểm được key kịp lúc. | Sau `Retry-After` | Retry. | + + ## Liên quan {#related} + + - [Hành vi chuẩn của API](../reference/behaviour.md): chính sách retry, rate limit, độ mới. + - [Xử lý sự cố](../production/troubleshooting.md): từ triệu chứng tới cách sửa. + - [Hỗ trợ](../help/support.md): cần gửi gì khi lỗi kéo dài.
- 02/10/2026 · +1 −1 dòng
Xem thay đổi
⋯ | `502`, `503`, các `5xx` khác | Có, với exponential backoff và giới hạn số lần, ví dụ 1 s, 2 s, 4 s, rồi dừng. | - Trong lúc phát, xin vé mới một lần khi Player SDK lỗi, sau đó làm theo bảng này. Xem [Playback](playback.md#expiry). + Trong lúc phát, xin vé mới một lần khi Player SDK lỗi, sau đó làm theo bảng này. Xem [Playback](playback.md#expiry). Jitter, ngân sách retry và code mẫu: xem [Phát mượt khi tải cao](../guides/smooth-playback.md#retry). ## Nhận trợ giúp ⋯
- 01/10/2026 · +2 −1 dòng
Xem thay đổi
⋯ | 400 | `invalid_device_info` | Một giá trị thiết bị trông như rỗng hoặc không hợp lệ, ví dụ chuỗi `"(null)"`. `fields` nêu các giá trị sai. | Sửa cách app đọc giá trị từ Player SDK. | | 401 | không có | API key bị thiếu, không hợp lệ hoặc đã bị thu hồi. | Kiểm tra key. Không retry. | - | 403 | không có | Key thiếu scope `playback`. | Dùng playback key mà Wandura cấp cho bạn. | + | 403 | không có | Key thiếu scope `playback`. | Dùng một playback key: tạo trên **Developers** → **Stream films in an app**. | | 403 | `not_entitled` | Tổ chức của bạn hiện không được cấp phép stream phim này. `reason` cho biết chi tiết. | Hiển thị trạng thái khoá hoặc không khả dụng. Không retry. | | 404 | `not_ready` | Tập hoặc phim không tồn tại, chưa publish, hoặc chưa sẵn sàng để stream. | Hiển thị "chưa khả dụng". Làm mới catalog. | ⋯ | 503 | `not_ready` | Hiện chưa có phiên bản phát được của tập này. | Hiển thị "chưa khả dụng". Thử lại sau. | | 503 | `service_unavailable` | Wandura chưa kiểm được API key kịp lúc. Key **không** sai. | Chờ đúng `Retry-After` giây rồi thử lại, có backoff. Đừng xoay key. | + | 503 | `service_unavailable` | Nhà cung cấp video chưa trả lời kịp (chỉ ở playback). Tập phim và key đều không có vấn đề. | Chờ đúng `Retry-After` giây (2) rồi thử lại, có backoff. | ### Các `reason` của `not_entitled` ⋯
- 01/10/2026 · +1 −1 dòng
Xem thay đổi
⋯ | Trường | Kiểu | Mô tả | |---|---|---| - | `error` | string | Thông điệp cho người đọc. Hãy ghi log, nhưng đừng parse. | + | `error` | string | Thông điệp cho người đọc. Hãy ghi log, nhưng đừng parse, trừ `403` của catalog bên dưới. | | `error_code` | string | Mã máy đọc được. Rẽ nhánh theo trường này. Một số lỗi không có trường này, bảng bên dưới ghi là "không có". | | `reason` | string | Chỉ có với `not_entitled`: lý do chi tiết, dùng cho log và hỗ trợ. | ⋯
- 01/10/2026 · +2 −2 dòng
Xem thay đổi
⋯ | 401 | không có | `Invalid or revoked API key` | Key không tồn tại hoặc đã bị thu hồi. | Kiểm tra key. Không retry. | | 403 | không có | `This API key does not have the metadata:read scope` | Key thiếu scope. | Dùng key có `metadata:read`. | - | 403 | không có | `org_suspended` | Quyền truy cập của tổ chức bạn đang bị tạm ngưng. | Liên hệ đầu mối đối tác Wandura. Không retry. | + | 403 | không có | `org_suspended` | Quyền truy cập của tổ chức bạn đang bị tạm ngưng. | Liên hệ Wandura. Không retry. | | 429 | `rate_limited` | | Đã chạm rate limit. | Chờ hết `Retry-After`. | | 503 | `service_unavailable` | `Could not verify the API key right now — retry` | Wandura chưa kiểm được key kịp lúc. Key **không** sai. | Chờ đúng `Retry-After` giây rồi thử lại, có backoff. Đừng xoay key. | ⋯ | 401 | 4011 | `Invalid or revoked API key` | Key không tồn tại hoặc đã bị thu hồi. | Kiểm tra key. Không retry. | | 403 | 4030 | `This API key does not have the creatives:export scope` | Key thiếu scope. | Dùng key có `creatives:export`. | - | 403 | 4031 | `org_suspended` | Quyền truy cập của tổ chức bạn đang bị tạm ngưng. | Liên hệ đầu mối đối tác Wandura. | + | 403 | 4031 | `org_suspended` | Quyền truy cập của tổ chức bạn đang bị tạm ngưng. | Liên hệ Wandura. | | 404 | 4040 | `Creative not found` | Chỉ với `GET /creatives/{id}`. Creative không tồn tại, thuộc tổ chức khác hoặc chưa được duyệt. | Gỡ nó khỏi tập creative đang dùng. | | 422 | 4220 | `limit must be an integer between 1 and 100` | Chỉ với endpoint liệt kê. `limit` sai. | Sửa request. | ⋯
- 30/09/2026 · +3 −0 dòng
Xem thay đổi
⋯ | 403 | không có | `org_suspended` | Quyền truy cập của tổ chức bạn đang bị tạm ngưng. | Liên hệ đầu mối đối tác Wandura. Không retry. | | 429 | `rate_limited` | | Đã chạm rate limit. | Chờ hết `Retry-After`. | + | 503 | `service_unavailable` | `Could not verify the API key right now — retry` | Wandura chưa kiểm được key kịp lúc. Key **không** sai. | Chờ đúng `Retry-After` giây rồi thử lại, có backoff. Đừng xoay key. | ## Lỗi playback {#playback-errors} ⋯ | 502 | không có | Wandura không chuẩn bị được stream hoặc không ký được play token. | Retry với backoff. | | 503 | `not_ready` | Hiện chưa có phiên bản phát được của tập này. | Hiển thị "chưa khả dụng". Thử lại sau. | + | 503 | `service_unavailable` | Wandura chưa kiểm được API key kịp lúc. Key **không** sai. | Chờ đúng `Retry-After` giây rồi thử lại, có backoff. Đừng xoay key. | ### Các `reason` của `not_entitled` ⋯ | 429 | không có (body phẳng, `error_code` `rate_limited`) | | Đã chạm rate limit. | Chờ hết `Retry-After`. | | 503 | 5030 | `The creative feed is temporarily unavailable` | Sự cố tạm thời phía Wandura. | Retry với backoff. | + | 503 | 5031 | `Could not verify the API key right now — retry` | Wandura chưa kiểm được key kịp lúc. Key **không** sai. | Retry với backoff. Đừng xoay key. | ## Hướng dẫn retry ⋯
- 29/09/2026 · Tạo trang