HTTP Status Code

Bởi vì Web Service thiết kế theo phương pháp Restful API dựa trên HTTPS nên các response trả về từ web service đều là HTTP Response, do đó, kèm theo HTTP Status Code. Dưới đây là các status code thường gặp trong HTTP Response của Hubport.

HTTP Status Code khi request thành côngCopy Anchor Link

HTTP Status Code khi request thất bại / có lỗiCopy Anchor Link

Định dạng response lỗiCopy Anchor Link

Khi có lỗi, response body là JSON với key error chứa danh sách mã lỗi. Một số lỗi có thêm key detail mô tả chi tiết:

{
  "error": ["error_company_locked"],
  "detail": { "reason": "suspended", "state": "suspended" }
}

Riêng lỗi Rate Limit (429) trả về body là mảng mã lỗi: ["error_rate_limit_exceed"].

Một số lỗi 4xx thường gặp khi gửi requestCopy Anchor Link

Phần lớn bạn bị các lỗi này là do khi gửi yêu cầu lên bị thiếu thông tin, các thông tin này đều được mô tả trong phần hướng dẫn của từng web service. Do đó, bạn cần đối chiếu kỹ đặc tả nếu phát hiện bị lỗi khi gửi yêu cầu, và các yêu cầu này thường là phương thức POST hoặc PUT để tạo hoặc cập nhật thông tin nào đó.

Lỗi xác thực bằng User Login Token (JWT)Copy Anchor Link

Lỗi xác thực bằng API KeyCopy Anchor Link

Lỗi phân quyền, gói dịch vụ và trạng thái cửa hàngCopy Anchor Link

Lỗi error_company_lockedCopy Anchor Link

Trả về khi cửa hàng của JWT / API Key đang bị khoá:

{
  "error": ["error_company_locked"],
  "detail": {
    "reason": "suspended",
    "state": "suspended"
  }
}

Khi cửa hàng bị khoá, hầu hết API đều trả lỗi này, chỉ còn một số API phục vụ tài khoản vẫn dùng được như: Đăng xuất, Thông tin người dùng hiện tại (/v1/usersessions/me...), Đổi công ty đang làm việc. Khi đăng nhập vào cửa hàng bị khoá, API đăng nhập cũng trả 403 error_company_locked.

Lỗi error_module_disabledCopy Anchor Link

Trả về khi API thuộc một module chưa được bật cho cửa hàng của JWT / API Key:

{
  "error": ["error_module_disabled"],
  "detail": { "module": "warehouse3d", "module_id": 9400 }
}

Một số API đọc mà POS dùng khi bán hàng không báo lỗi mà trả 200 với danh sách rỗng và field module_disabled (ví dụ GET /v1/flashsales/by-product/{id} khi shop không dùng module Khuyến mãi); các API tính khuyến mãi của đơn (/v1/promotionengines/*, /v1/promotionchecks/*) trả "không có khuyến mãi" để đơn vẫn tạo được với giá gốc.

Lỗi này không phụ thuộc gói dịch vụ (khác 402 error_feature_requires_plan): nâng gói không bật được module. Các API khác của cửa hàng vẫn dùng bình thường. Module được bật lại thì API dùng được ngay ở request kế tiếp.

Các lỗi chung khác: 404 error_not_found (không tìm thấy dữ liệu / đường dẫn), 405 error_method_not_allowed (đường dẫn có nhưng không hỗ trợ phương thức HTTP này), 422 error_not_permission (không có quyền với dữ liệu này). Đường dẫn API không tồn tại trả 404 error_not_found dạng JSON kèm header CORS như mọi API (trình duyệt đọc được mã lỗi thay vì báo lỗi CORS).