Mã lỗi

Cách xử lý lỗi của API Tools HiTechCloud: phản hồi JSON ok:false kèm mã error ổn định và message, danh mục mã HTTP (401, 403, 404, 429, 503) và mã lỗi chuỗi.

Xem Markdown
json
{
  "ok": false,
  "error": "invalid_api_key",
  "message": "Khoá API không đúng. Kiểm tra lại trong portal."
}

Hãy xử lý theo error (ổn định) chứ không theo message (có thể đổi lời).

Mã HTTP

MãÝ nghĩaCách xử lý
200Thành công.—
401Thiếu hoặc sai khoá API.Gửi header X-API-Key đúng khoá còn hiệu lực.
403Khoá không đủ quyền hoặc IP không được phép.Sửa phạm vi khoá / danh sách IP trong Cổng khách hàng.
404Không có dữ liệu tương ứng.Kiểm tra lại giá trị truyền vào; có endpoint dùng 404 để báo “còn trống”.
422Tham số chưa hợp lệ.Đọc message / errors để sửa tham số.
429Vượt tốc độ hoặc hạn mức.Chờ theo header Retry-After rồi thử lại, hoặc nâng hạn mức.
503Nguồn dữ liệu hoặc endpoint tạm ngừng.Thử lại sau (có Retry-After); dữ liệu đệm vẫn dùng được.

Mã lỗi `error`

MãHTTPNguyên nhân
missing_api_key401Không có header X-API-Key.
invalid_api_key401Khoá không tồn tại.
revoked_api_key401Khoá đã bị thu hồi.
expired_api_key401Khoá đã hết hạn.
ip_not_allowed403IP gọi không nằm trong danh sách cho phép của khoá.
scope_not_allowed403Khoá không được cấp nhóm dịch vụ này.
admin_key_required403Endpoint chỉ dành cho khoá quản trị.
endpoint_grant_required403Endpoint hạn chế — cần xin quyền riêng.
organization_suspended403Tổ chức đang bị đình chỉ.
owner_banned / owner_deleted403Chủ khoá bị khoá hoặc đã bị xoá.
rate_limit_exceeded429Vượt số lượt gọi mỗi phút của khoá.
user_rate_limit_exceeded429Vượt tốc độ riêng của tài khoản.
user_quota_exceeded429Hết hạn mức tháng của tài khoản.
endpoint_rate_limit_exceeded429Endpoint này giới hạn tốc độ riêng.
endpoint_disabled503Endpoint tạm ngừng phục vụ.
target_not_allowed422Giá trị truyền vào trỏ tới địa chỉ nội bộ / không được phép.