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.
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ĩa | Cách xử lý |
|---|---|---|
| 200 | Thành công. | — |
| 401 | Thiếu hoặc sai khoá API. | Gửi header X-API-Key đúng khoá còn hiệu lực. |
| 403 | Khoá 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. |
| 404 | Khô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”. |
| 422 | Tham số chưa hợp lệ. | Đọc message / errors để sửa tham số. |
| 429 | Vượ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. |
| 503 | Nguồ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ã | HTTP | Nguyên nhân |
|---|---|---|
missing_api_key | 401 | Không có header X-API-Key. |
invalid_api_key | 401 | Khoá không tồn tại. |
revoked_api_key | 401 | Khoá đã bị thu hồi. |
expired_api_key | 401 | Khoá đã hết hạn. |
ip_not_allowed | 403 | IP gọi không nằm trong danh sách cho phép của khoá. |
scope_not_allowed | 403 | Khoá không được cấp nhóm dịch vụ này. |
admin_key_required | 403 | Endpoint chỉ dành cho khoá quản trị. |
endpoint_grant_required | 403 | Endpoint hạn chế — cần xin quyền riêng. |
organization_suspended | 403 | Tổ chức đang bị đình chỉ. |
owner_banned / owner_deleted | 403 | Chủ khoá bị khoá hoặc đã bị xoá. |
rate_limit_exceeded | 429 | Vượt số lượt gọi mỗi phút của khoá. |
user_rate_limit_exceeded | 429 | Vượt tốc độ riêng của tài khoản. |
user_quota_exceeded | 429 | Hết hạn mức tháng của tài khoản. |
endpoint_rate_limit_exceeded | 429 | Endpoint này giới hạn tốc độ riêng. |
endpoint_disabled | 503 | Endpoint tạm ngừng phục vụ. |
target_not_allowed | 422 | Giá trị truyền vào trỏ tới địa chỉ nội bộ / không được phép. |
Hãy xử lý theo error (ổn định) chứ không theo message (có thể đổi lời).
Mã HTTP
| Mã | Ý nghĩa | Cách xử lý |
|---|---|---|
| 200 | Thành công. | — |
| 401 | Thiếu hoặc sai khoá API. | Gửi header X-API-Key đúng khoá còn hiệu lực. |
| 403 | Khoá 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. |
| 404 | Khô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”. |
| 422 | Tham số chưa hợp lệ. | Đọc message / errors để sửa tham số. |
| 429 | Vượ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. |
| 503 | Nguồ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ã | HTTP | Nguyên nhân |
|---|---|---|
missing_api_key | 401 | Không có header X-API-Key. |
invalid_api_key | 401 | Khoá không tồn tại. |
revoked_api_key | 401 | Khoá đã bị thu hồi. |
expired_api_key | 401 | Khoá đã hết hạn. |
ip_not_allowed | 403 | IP gọi không nằm trong danh sách cho phép của khoá. |
scope_not_allowed | 403 | Khoá không được cấp nhóm dịch vụ này. |
admin_key_required | 403 | Endpoint chỉ dành cho khoá quản trị. |
endpoint_grant_required | 403 | Endpoint hạn chế — cần xin quyền riêng. |
organization_suspended | 403 | Tổ chức đang bị đình chỉ. |
owner_banned / owner_deleted | 403 | Chủ khoá bị khoá hoặc đã bị xoá. |
rate_limit_exceeded | 429 | Vượt số lượt gọi mỗi phút của khoá. |
user_rate_limit_exceeded | 429 | Vượt tốc độ riêng của tài khoản. |
user_quota_exceeded | 429 | Hết hạn mức tháng của tài khoản. |
endpoint_rate_limit_exceeded | 429 | Endpoint này giới hạn tốc độ riêng. |
endpoint_disabled | 503 | Endpoint tạm ngừng phục vụ. |
target_not_allowed | 422 | Giá trị truyền vào trỏ tới địa chỉ nội bộ / không được phép. |
json
{
"ok": false,
"error": "invalid_api_key",
"message": "Khoá API không đúng. Kiểm tra lại trong portal."
}