Trường response_code trong response của các API FX sử dụng các mã dưới đây. Một số mã chỉ áp dụng cho API cụ thể, được ghi chú ở cột "Áp dụng".
Mã lỗi chung (tất cả API)
| Mã | Thông báo | Mô tả | Áp dụng |
|---|
| 200 | Success | Request được xử lý thành công | Tất cả |
| 101 | System Error | Lỗi không mong muốn phía Baokim | Tất cả |
| 110 | Merchant code invalid | merchant_code không xác định hoặc không được phép | Tất cả |
| 120 | Invalid signature | Header Signature không hợp lệ | Tất cả |
| 422 | Validation Error | Trường request thiếu hoặc không hợp lệ | Tất cả |
| 429 | Too many requests | Merchant vượt quá giới hạn tỷ lệ (rate limit) | Tất cả |
Mã lỗi riêng theo API
Lấy báo giá FX
| Mã | Thông báo | Mô tả |
|---|
| 404 | Currency not supported | Ngoại tệ yêu cầu không nằm trong danh mục Merchant |
| 423 | FX rate temporarily unavailable | Không có tỷ giá tin cậy khả dụng vào lúc yêu cầu |
Validation rules cụ thể:
- Không có VND trong cặp tiền → mã 422
- trade_type không khớp chiều (SELL với ngoại tệ → VND, BUY với VND → ngoại tệ) → mã 422
amount ≤ 0 hoặc không phải số nguyên khi fixed_side về phía VND → mã 422
Thực thi chuyển đổi
| Mã | Thông báo | Mô tả |
|---|
| 425 | Quote not found, expired, or does not belong to merchant | quote_id không tồn tại, vượt expires_at, hoặc không thuộc merchant này |
| 426 | Quote already used | quote_id đã được thực thi thành công trước đó (single-use) |
| 427 | Insufficient balance | Merchant không đủ tiền nguồn để chuyển đổi |
| 428 | Amount/currency does not match quote | from_currency hoặc from_amount không khớp giá trị trong quote |
Ghi chú: Timeout hoặc mất kết nối khi gọi API này không đồng nghĩa lệnh thất bại. Sử dụng Tra cứu lệnh chuyển đổi để xác định trạng thái cuối cùng.
Tra cứu lệnh chuyển đổi
| Mã | Thông báo | Mô tả |
|---|
| 430 | Conversion not found | Không tìm thấy lệnh với conversion_id hoặc origin_request_id được cung cấp |
Timeout recovery: Nếu tra theo origin_request_id mà nhận mã 430 = lệnh gốc chưa được ghi nhận phía Baokim, Merchant an toàn để retry Thực thi chuyển đổi với cùng request_id.
Lấy lịch sử tỷ giá
| Mã | Thông báo | Mô tả |
|---|
| 404 | Currency not supported | Ngoại tệ yêu cầu không nằm trong danh mục Merchant |
| 416 | Invalid date range | to_date < from_date, khoảng > 30 ngày, hoặc to_date > ngày hiện tại |