Khái niệm
Trên trang này
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ý.
Định dạng lỗi
Catalog và playback
{
"error": "Episode not found or not ready to stream",
"error_code": "not_ready"
}| 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. |
Creative
{
"code": 4011,
"message": "Invalid or revoked API key",
"server_time": 1790679032
}| 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. |
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.
Xử lý lỗi theo mã
- Rẽ nhánh theo
error_code(hoặccodevớ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
errorhaymessagecho người xem. Hãy ánh xạ mã sang nội dung của riêng bạn.
Lỗi catalog
GET /api/delivery/v1/catalog
| Status | error_code |
Thông điệp | Ý nghĩa | Cách xử lý |
|---|---|---|---|---|
| 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. |
Lỗi playback
POST /api/delivery/v1/playback
| 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. |
Các reason của not_entitled
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.
reason |
Ý nghĩa |
|---|---|
org_suspended |
Quyền truy cập của tổ chức bạn đang bị tạm ngưng. |
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. |
Lỗi creative
GET /api/delivery/v1/creatives và GET /api/delivery/v1/creatives/{id}
| Status | code |
Thông điệp | Ý nghĩa | Cách xử lý |
|---|---|---|---|---|
| 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. |
Hướng dẫn retry
| 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. |
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.
Nhận trợ giúp
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ợ.
Cập nhật 01/10/2026 · Lịch sử thay đổi (5)