# Lỗi & giới hạn

## Mã HTTP

| Mã | Ý nghĩa | Nên làm |
|---|---|---|
| `200` | Thành công | |
| `400` | Yêu cầu sai: thiếu tham số, sai kiểu dữ liệu | Sửa yêu cầu theo `message` |
| `403` | API key sai, hết quyền, hoặc không đủ quyền với thao tác này | Kiểm tra key và quyền; không thử lại nguyên trạng |
| `404` | Không tìm thấy cửa hàng hoặc bản ghi | Kiểm tra mã trong đường dẫn |
| `422` | Dữ liệu không hợp lệ về nghiệp vụ | Sửa dữ liệu theo `message` |
| `429` | Vượt giới hạn tần suất (mã `106`) hoặc nhập sai key quá nhiều lần (mã `109`) | Chờ rồi thử lại (xem bên dưới) |
| `500`, `502`, `503`, `504` | Lỗi phía máy chủ hoặc tạm thời quá tải | Thử lại sau, tăng dần thời gian chờ |

## Nội dung lỗi

Lỗi trả JSON có `success: false`:

```json
{
  "success": false,
  "message": "You have reached the limit of requests",
  "error_code": 106
}
```

| Trường | Ý nghĩa |
|---|---|
| `success` | Luôn `false` khi lỗi |
| `message` | Mô tả lỗi cho người đọc, có thể đổi câu chữ theo thời gian |
| `error_code` | Mã lỗi dạng số (nếu có). Dùng trường này, không dựa vào `message`, để xử lý trong code |
| `error` | Tên lỗi ổn định dạng chữ (nếu có) |
| `message_code` | Mã thông báo nghiệp vụ của POS (nếu có) |
| `permission` | Quyền còn thiếu khi bị từ chối (nếu có) |

Mã lỗi thường gặp:

| `error_code` | HTTP | Ý nghĩa |
|---|---|---|
| `105` | 403 | `api_key` không hợp lệ |
| `106` | 429 | Vượt giới hạn tần suất |
| `109` | 429 | Nhập sai `api_key` quá nhiều lần, bị khoá 5 phút |

## Giới hạn tần suất

Giới hạn tính theo từng endpoint (mã bản ghi trong đường dẫn không tính riêng) và theo:

- **API key cửa hàng**: cửa hàng. Mọi key của cùng cửa hàng dùng chung hạn mức.
- **API key tài khoản**: tài khoản + cửa hàng.

| Loại yêu cầu | Giới hạn |
|---|---|
| Đọc (`GET`) | Dưới 30 yêu cầu mỗi giây |
| Ghi (`POST`, `PUT`, `DELETE`) | Dưới 100 yêu cầu mỗi giây |
| `GET /shops/{SHOP_ID}/inventory_histories` | 3 yêu cầu mỗi giây |

Vượt giới hạn trả `429` với `error_code` `106`.

## Thử lại

- `429` và lỗi `5xx`: chờ rồi thử lại, tăng dần thời gian chờ (ví dụ 1, 2, 4, 8 giây), dừng sau vài lần. Có header `Retry-After` thì chờ đúng số giây đó.
- Lỗi `4xx` khác: sửa yêu cầu; gửi lại nguyên trạng vẫn lỗi.
- Yêu cầu ghi (`POST`) bị lỗi mạng hoặc hết thời gian chờ: kiểm tra bản ghi đã được tạo chưa trước khi gửi lại, tránh tạo trùng.
- Đồng bộ số lượng lớn: chạy tuần tự hoặc ít luồng song song, dùng `page_size` lớn thay vì nhiều yêu cầu nhỏ.