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ờ

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ính theo từng endpoint (mã bản ghi trong đường dẫn không tính riêng) và theo:

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.

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