Danh mục mã lỗi hoàn chỉnh
| HTTP Code | Mã lỗi (error.code) | Ý nghĩa nghiệp vụ | Cách xử lý |
|---|---|---|---|
| 200 | SUCCESS | Tra cứu thành công, tìm thấy chủ tài khoản | Sử dụng data.accountName và signature |
| 400 | INVALID_BANK_CODE | Mã ngân hàng không đúng hoặc không hỗ trợ | Kiểm tra bảng mã bankCode trong danh mục |
| 400 | INVALID_ACCOUNT_NUMBER | Số tài khoản rỗng hoặc không đúng quy cách | Kiểm tra định dạng chuỗi số tài khoản |
| 401 | UNAUTHORIZED_API_KEY | Khóa API không hợp lệ hoặc đã bị khóa | Kiểm tra header X-API-Key trên Dashboard |
| 402 | PAYMENT_REQUIRED | Số dư ví hoặc số lượt trong gói đã cạn kiệt | Nạp tiền vào ví hoặc gia hạn gói lượt |
| 403 | IP_NOT_ALLOWED | Địa chỉ IP của máy chủ không có trong Whitelist | Thêm IP máy chủ vào Dashboard > API Keys |
| 403 | QUOTA_EXHAUSTED | Hạn mức của riêng API Key này đã hết | Tăng hạn mức cho khóa trong trang quản trị |
| 404 | NOT_FOUND | Số tài khoản không tồn tại tại ngân hàng đích | Thông báo cho khách hàng kiểm tra lại STK |
| 409 | IDEMPOTENCY_PAYLOAD_MISMATCH | Dùng lại Idempotency-Key nhưng đổi dữ liệu | Sinh Idempotency-Key mới cho giao dịch mới |
| 429 | RATE_LIMIT_EXCEEDED | Gọi vượt quá số lượt cho phép trong 1 giây | Hạ nhịp gọi hoặc chờ theo header Retry-After |
| 503 | ENDPOINT_MAINTENANCE | Cổng API đang tạm ngưng bảo trì theo lịch | Tạm hoãn và gọi lại sau thời gian autoReopenAt |
| 502 | UPSTREAM_FAILURE | Cổng Napas / Ngân hàng đích tạm thời gián đoạn | Thử lại sau 3-5 giây (Miễn phí 100%) |