Tài liệu mã trạng thái API nền tảng mở
Giới thiệu tài liệu
Tài liệu này quy định chuẩn mã trạng thái mà API nền tảng mở trả về, nhằm làm rõ kết quả gọi API, loại lỗi và nguyên nhân, giúp nhà phát triển xác định và xử lý sự cố nhanh chóng. Mọi API đều tuân theo quy tắc mã trạng thái này khi trả kết quả.
Quy tắc phân loại mã trạng thái
| Dải mã | Mô tả phân loại |
|---|---|
| 200 | Thành công (gọi API hoàn tất bình thường) |
| 1xxxx | Lỗi chung (ngoại lệ không phân loại) |
| 2xxxx | Lỗi liên quan xác thực và ủy quyền |
| 4xxxx | Lỗi liên quan kiểm tra yêu cầu/tham số |
| 5xxxx | Lỗi liên quan API |
| 6xxxx | Lỗi liên quan giới hạn tần suất |
| 7xxxx | Lỗi liên quan logic nghiệp vụ |
Chi tiết mã trạng thái
1. Mã trạng thái thành công
| Mã trạng thái | Định danh enum | Mô tả |
|---|---|---|
| 200 | SUCCESS | Gọi API thành công |
2. Lỗi chung (1xxxx)
| Mã trạng thái | Định danh enum | Mô tả |
|---|---|---|
| 10000 | UNKNOWN_ERROR | Lỗi không xác định, vui lòng liên hệ bộ phận hỗ trợ kỹ thuật |
3. Lỗi liên quan xác thực và ủy quyền (2xxxx)
| Mã trạng thái | Định danh enum | Mô tả |
|---|---|---|
| 20001 | API_KEY_MISSING | Thiếu khóa API (yêu cầu không mang tham số API Key) |
| 20002 | API_KEY_INVALID | Khóa API không hợp lệ (đã vô hiệu, hết hạn hoặc chưa được phê duyệt) |
| 20010 | TIMESTAMP_MISSING | Thiếu tham số dấu thời gian (yêu cầu không mang tham số timestamp) |
| 20011 | TIMESTAMP_FORMAT_ERROR | Sai định dạng dấu thời gian (phải là số 10 hoặc 13 chữ số) |
| 20012 | TIMESTAMP_EXPIRED | Dấu thời gian đã hết hạn (yêu cầu quá hạn, cần tạo lại dấu thời gian rồi gọi lại) |
| 20020 | SIGNATURE_MISSING | Thiếu tham số chữ ký (yêu cầu không mang tham số signature) |
| 20021 | SIGNATURE_VERIFY_FAILED | Xác minh chữ ký thất bại (quy tắc tạo chữ ký sai hoặc tham số bị chỉnh sửa) |
4. Lỗi liên quan kiểm tra yêu cầu/tham số (4xxxx)
| Mã trạng thái | Định danh enum | Mô tả |
|---|---|---|
| 400 | INVALID_REQUEST | Không thể phân tích phần thân yêu cầu (cần kiểm tra cách truyền tham số có đúng tài liệu không) |
| 404 | NOT_FOUND | Đường dẫn API không tồn tại (cần kiểm tra đường dẫn yêu cầu) |
| 405 | REQUEST_METHOD_NOT_ALLOWED | Phương thức yêu cầu không được phép (cần kiểm tra phương thức có đúng tài liệu không) |
| 40001 | REQUIRED_PARAMS_EMPTY | Thiếu tham số bắt buộc (chưa gửi tham số bắt buộc theo yêu cầu API) |
| 40002 | REQUIRED_PARAMS_ILLEGAL | Tham số yêu cầu không hợp lệ (định dạng hoặc giá trị ngoài phạm vi cho phép) |
5. Lỗi liên quan API (5xxxx)
| Mã trạng thái | Định danh enum | Mô tả |
|---|---|---|
| 50001 | INTERFACE_NOT_FOUND | API không tồn tại (sai đường dẫn yêu cầu) |
6. Lỗi liên quan giới hạn tần suất (6xxxx)
| Mã trạng thái | Định danh enum | Mô tả |
|---|---|---|
| 60001 | INTERFACE_RATE_LIMIT | Tần suất gọi API vượt giới hạn, vui lòng thử lại sau |
7. Lỗi liên quan logic nghiệp vụ (7xxxx)
| Mã trạng thái | Định danh enum | Mô tả |
|---|---|---|
| 70001 | NOT_ENOUGH_CREDIT | Số dư tài khoản không đủ, vui lòng nạp tiền |