DANIXTài liệu nhà phát triển
Tài liệu nhà phát triểnBản Markdownopenapi.jsonllms.txt

Lỗi

Mọi lỗi của /api/open/v1 có dạng RFC 9457 (application/problem+json) kèm trường code ổn định:

{
  "type": "https://danix.vn/developers/errors#rate-limited",
  "title": "Vượt hạn mức gọi API, hãy chờ rồi thử lại",
  "status": 429,
  "code": "rate-limited",
  "detail": "Chờ 12 giây rồi thử lại."
}
Trường Ý nghĩa
type Địa chỉ giải thích loại lỗi; phần neo #… chính là code.
title Tên ngắn của loại lỗi, ổn định theo code.
status Mã trạng thái HTTP.
code Mã máy đọc, chữ thường nối bằng gạch ngang. Dùng trường này để rẽ nhánh xử lý, không dùng title hay detail.
detail Mô tả cho đúng lượt lỗi này, dành cho người đọc; câu chữ có thể đổi.
errors Chỉ có ở validation-failed, khi lỗi gắn với trường cụ thể (thân, query hay tham số đường dẫn sai hình dạng): danh sách trường sai, mỗi phần tử gồm path (đường tới trường, ví dụ lines.0.quantity) và message (vì sao sai). Từ chối nghiệp vụ không gắn với một trường (ví dụ mẫu mã không tồn tại trong shop) chỉ có detail.

Client cần bỏ qua trường lạ trong thân lỗi, và coi code lạ như lỗi cùng nhóm với status của nó. Danh sách code có thể được bổ sung mà không đổi phiên bản.

Cách xử lý theo nhóm

  • 400, 413, 415 và 422: request sai, thử lại y nguyên sẽ sai tiếp. Sửa request.
  • 401 và 403: vấn đề khoá hay quyền, không phải mạng. Đừng thử lại dồn dập; kiểm tra khoá và quyền.
  • 402: gói của shop hết hạn; chờ shop gia hạn.
  • 404: không có bản ghi, hoặc bản ghi thuộc shop khác, hoặc trang chat ngoài danh sách của khoá. Cố ý không phân biệt ba trường hợp này.
  • 409: xung đột trạng thái hoặc lượt trước còn chạy. Một số mã dặn thử lại sau một lúc.
  • 429: chờ theo Retry-After; xem Hạn mức gọi.
  • 5xx: lỗi phía DANIX, hãng vận chuyển (503 carrier-unavailable) hoặc kênh chat (503 channel-unavailable). Thử lại với khoảng chờ tăng dần; dùng Idempotency-Key để thử lại không tạo trùng.

Bảng mã lỗi

validation-failed

400. Thân, tham số query hoặc tham số đường dẫn không hợp lệ, hoặc dữ liệu hợp lệ về hình dạng nhưng không dùng được (ví dụ mã tham chiếu không có trong shop). Khi lỗi gắn với trường cụ thể, mảng errors chỉ rõ từng trường (path và message); từ chối không gắn với một trường chỉ có detail. Sửa theo đó rồi gửi lại.

invalid-cursor

400. cursor sai hình dạng hoặc không phải giá trị API đã trả. Bắt đầu lại từ trang đầu, hoặc dùng đúng nextCursor của trang trước. Xem Phân trang và đồng bộ.

api-key-not-accepted

400. Bạn gửi khoá API tới đường đăng xuất hoặc đường đăng ký thông báo đẩy, vốn chỉ dành cho phiên đăng nhập của người dùng. Các đường khác ngoài /api/open/v1 nhận 401 như khi chưa đăng nhập. Khoá API chỉ dùng cho /api/open/v1.

invalid-api-key

401. Thiếu header Authorization, khoá sai định dạng, không tồn tại, đã thu hồi hoặc đã hết hạn. Kiểm tra khoá; nếu vừa xoay, dùng khoá mới. Không thử lại cùng khoá.

subscription-expired

402. Gói của shop đã hết hạn nên shop ở chế độ chỉ đọc; chỉ request ghi bị từ chối, request GET vẫn chạy. Shop gia hạn gói là hết lỗi.

insufficient-permission

403. Khoá không có quyền cho đường này, hoặc thân yêu cầu dùng một trường cần quyền riêng (ví dụ đặt unitPrice khác giá niêm yết, giảm giá hay ghi payments khi tạo đơn). Quyền cần có — và "Quyền thêm theo trường" — ghi ở từng endpoint trong phần tham chiếu. Nhờ quản trị viên shop bổ sung quyền cho ứng dụng kết nối.

shop-suspended

403. Shop đang bị đình chỉ. Mọi request bị từ chối cho tới khi shop được mở lại.

automation-not-active

403. Gói của shop không có tính năng Tự động hoá nên khoá API không dùng được. Shop cần nâng gói.

not-found

404. Không có bản ghi hoặc đường dẫn này với khoá của bạn. Cũng là kết quả khi bản ghi thuộc shop khác hoặc trang chat nằm ngoài danh sách được chọn cho khoá.

conflict

409. Thao tác xung đột với trạng thái hiện tại (ví dụ đơn đã ở trạng thái không cho phép bước này). Đọc lại bản ghi rồi quyết định.

idempotency-key-in-progress

409. Lượt trước dùng cùng Idempotency-Key vẫn đang chạy. Phản hồi trả ngay, kèm Retry-After: 1. Chờ rồi gửi lại y nguyên request; đừng đổi khoá. Xem Idempotency-Key.

idempotency-key-reused

422. Idempotency-Key này đã dùng cho một request có thân khác. Mỗi khoá chỉ gắn với một nội dung; dùng khoá mới cho nội dung mới.

payload-too-large

413. Thân yêu cầu vượt quá dung lượng máy chủ nhận. Thân của mọi endpoint đều nhỏ (một đơn tối đa 200 dòng hàng); gặp mã này là request đang gửi thứ không cần thiết. Thu gọn thân, đừng thử lại y nguyên.

unsupported-media-type

415. Thân yêu cầu không phải JSON. Gửi kèm header Content-Type: application/json và thân JSON hợp lệ.

rate-limited

429. Vượt hạn mức của khoá. Chờ đủ thời gian trong header Retry-After (số giây) rồi thử lại. Xem Hạn mức gọi.

internal-error

500. Lỗi phía DANIX. Thử lại với khoảng chờ tăng dần; nếu lỗi kéo dài, liên hệ hỗ trợ kèm thời điểm và đường dẫn đã gọi.

carrier-unavailable

503. Hãng vận chuyển hiện không với tới được (mạng, hãng đang lỗi hoặc kết nối của shop chưa dùng được), nên thao tác tạo hay huỷ vận đơn chưa hoàn tất. Thử lại sau một lúc với khoảng chờ tăng dần; trước khi tạo lại, đọc GET /shipments?orderId=… để biết lượt trước đã để lại vận đơn nào chưa. Lỗi kéo dài thì báo quản trị viên shop kiểm tra kết nối hãng.

channel-unavailable

503. Kênh chat (Facebook, Zalo) tạm thời không phản hồi — kênh đang giới hạn tốc độ gọi của trang, máy chủ của kênh lỗi hoặc mạng chập chờn — nên thao tác gửi tin, nhắn riêng hay ẩn, hiện bình luận chưa hoàn tất. Khác rate-limited: đây không phải hạn mức của khoá API. Thử lại sau một lúc với khoảng chờ tăng dần.

order-has-live-shipment

409. Đơn còn vận đơn chưa kết thúc nên không thực hiện được thao tác này (ví dụ sửa nội dung hàng). Huỷ hoặc chờ vận đơn kết thúc, rồi thao tác lại.

order-status-not-allowed

422. Không chuyển được đơn sang trạng thái này từ trạng thái hiện tại. Đọc lại đơn để biết trạng thái hiện hành rồi chọn bước hợp lệ.

insufficient-stock

422. Không đủ tồn kho cho thao tác này. Kiểm tra tồn kho bằng GET /inventory/stock, giảm số lượng hoặc nhập thêm hàng rồi thử lại.

variant-removed

422. Một mẫu mã trong request đã bị gỡ khỏi sản phẩm. Lấy lại sản phẩm để biết mẫu mã còn hiệu lực.

duplicate-code

409. Mã bạn đặt (mã đơn, mã sản phẩm…) đã tồn tại trong shop. Chọn mã khác.

customer-blocked

422. Khách hàng đang bị chặn nên không thực hiện được thao tác này.

document-already-posted

409. Phiếu kho đã ghi sổ rồi nên không ghi sổ lại hay sửa được.

shipment-not-cancellable

409. Vận đơn không còn huỷ được ở trạng thái hiện tại. Đọc GET /shipments/:id để xem trạng thái và hành trình.

messaging-window-closed

422. Đã quá khung thời gian nền tảng cho phép nhắn cho khách này (ví dụ 24 giờ với Facebook). Chỉ gửi lại được khi khách nhắn tin mới.

page-not-connected

422. Trang chat của hội thoại không còn kết nối nên không gửi được. Quản trị viên shop cần nối lại trang.

conversation-not-replyable

422. Hội thoại này không trả lời được qua API ở trạng thái hiện tại.

Trang trướcXác thựcTrang sauHạn mức gọi