Lỗi và giới hạn của API nền tảng

Lỗi của API nền tảng dùng cấu trúc body khác với lỗi của endpoint mô hình: mã trạng thái HTTP mang kết quả, còn body JSON luôn có success và, khi thất bại, có thêm code máy đọc được.

Định dạng phản hồi

Khi thành công, trả về HTTP 200:

{
  "success": true,
  "message": "",
  "data": {}
}

Khi thất bại, mã trạng thái HTTP thực tế được sử dụng và body có code máy đọc được:

{
  "success": false,
  "message": "Invalid Management Key",
  "code": "invalid_token"
}

message được bản địa hóa và có thể thay đổi giữa các phiên bản. Hãy dùng mã trạng thái HTTP và code trong logic chương trình.

Mã lỗi

HTTP	code	Tình huống
400	invalid_request	Tham số không hợp lệ, chẳng hạn số tiền ngoài phạm vi, tên bị thiếu hoặc quá dài khi tạo Key, status khác 1 / 2, bật một Key vẫn còn hết hạn hoặc hết hạn mức, thời gian hết hạn không hợp lệ, phân trang hoặc khoảng thời gian không hợp lệ, hoặc ; chưa mã hóa trong query
401	invalid_token	Thiếu header Authorization, key sai định dạng, hoặc key không tồn tại hay đã bị xóa
401	token_expired	Management Key đã hết hạn
401	token_revoked	Management Key đã bị thu hồi (chỉ với key cũ; key mới chỉ có thể xóa)
403	user_disabled	Tài khoản của chủ sở hữu Management Key đã bị vô hiệu hóa
403	insufficient_scope	Management Key không có quyền mà endpoint này yêu cầu
404	not_found	API Key không tồn tại hoặc không thuộc về bạn (không phân biệt); hoặc đường dẫn không tồn tại dưới /api/open/v1
405	method_not_allowed	Đường dẫn tồn tại nhưng không hỗ trợ phương thức HTTP này
429	rate_limited	Vượt giới hạn tần suất theo Management Key
500	internal_error	Lỗi máy chủ; không trả về chi tiết nội bộ

Đường dẫn không tồn tại dưới /api/open/v1 trả về 404, phương thức HTTP sai trả về 405, cả hai dùng chung body lỗi ở trên; dùng code để phân biệt «thử lại với phương thức khác» và «sai đường dẫn hoặc tham số».

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

Phạm vi	Giới hạn	Áp dụng cho	Phản hồi khi vượt giới hạn
Theo Management Key	120 yêu cầu/phút	Tất cả endpoint API nền tảng	429, code là rate_limited
Theo người dùng	30 yêu cầu/phút (mặc định)	Log của tài khoản, Xuất log, Mức sử dụng, Mức sử dụng theo mô hình, Mức sử dụng theo Key	429, body có thể trống
Theo IP client	180 yêu cầu/180 giây (mặc định)	Dùng chung cho tất cả endpoint /api	429
Theo IP client	100 yêu cầu/20 phút (mặc định)	Các endpoint nhạy cảm như Xem API Key đầy đủ	429, body có thể trống

Hãy xử lý giới hạn tần suất theo mã trạng thái HTTP. Khi nhận 429, hãy giảm tốc độ và thử lại sau.

Các endpoint mô hình dùng định dạng lỗi và giới hạn riêng; xem Lỗi thường gặp.