Lỗi

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.

Định dạng lỗi#

Định dạng phẳng#

Catalog, playback, cấu hình và video mở dùng một object phẳng:

{
  "error": "Episode not found or not ready to stream",
  "error_code": "not_ready"
}

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#

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:

{
  "code": 4011,
  "message": "Invalid or revoked API key",
  "server_time": 1790679032
}

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.

Request id#

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.

Xử lý lỗi theo mã#

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#

Đượ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#

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.

Mọi endpoint#

Mọi path#

Catalog#

GET /api/delivery/v1/catalog

Liệt kê bộ phim#

GET /api/delivery/v1/series

Lấy metadata một bộ phim#

GET /api/delivery/v1/series/{code}

Playback#

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

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ô)

Đừ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.

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#

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.

Cấu hình#

GET /api/delivery/v1/config

Liệt kê creative#

GET /api/delivery/v1/creatives

Lấy một creative#

GET /api/delivery/v1/creatives/{id}

Liệt kê video mở#

GET /api/delivery/v1/videos

Lấy một video mở#

GET /api/delivery/v1/videos/{id}

Liên quan#

• Hành vi chuẩn của API: chính sách retry, rate limit, độ mới.
• Xử lý sự cố: từ triệu chứng tới cách sửa.
• Hỗ trợ: cần gửi gì khi lỗi kéo dài.