# 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.

_Nguồn: https://developers.hitechcloud.vn/tai-lieu/ma-loi · Tài liệu HiTechCloud Developers_

```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. |
