The response_code field in API responses uses the codes below. Some codes apply to specific APIs only, noted in the "Applies to" column.
Common Error Codes (All APIs)
| Code | Message | Description | Applies to |
|---|
| 200 | Success | Request processed successfully | All |
| 101 | System Error | Unexpected error on Baokim's side | All |
| 110 | Invalid Merchant Code | merchant_code is undefined or not permitted | All |
| 120 | Invalid Signature | Header Signature is invalid | All |
| 422 | Validation Error | Request field is missing or invalid | All |
| 429 | Too Many Requests | Merchant exceeded rate limit | All |
API-Specific Error Codes
Get FX Quote
| Code | Message | Description |
|---|
| 404 | Currency Not Supported | Requested foreign currency is not in Merchant's configuration |
| 423 | FX Rate Temporarily Unavailable | No reliable rate available at this time |
Specific validation rules:
- Missing VND in currency pair → code 422
- trade_type does not match direction (SELL with foreign→VND, BUY with VND→foreign) → code 422
amount ≤ 0 or not integer when fixed_side specifies VND side → code 422
Create Conversion
| Code | Message | Description |
|---|
| 425 | Quote Not Found, Expired, or Not Belonging to Merchant | quote_id does not exist, beyond expires_at, or does not belong to this merchant |
| 426 | Quote Already Used | quote_id was already executed successfully (single-use constraint) |
| 427 | Insufficient Balance | Merchant does not have enough source currency to execute the conversion |
| 428 | Amount/Currency Mismatch with Quote | from_currency or from_amount does not match the quote |
Note: Timeout or connection loss when calling this API does not mean the order failed. Use Get Conversion Detail to determine the final status.
Get Conversion Detail
| Code | Message | Description |
|---|
| 430 | Conversion Order Not Found | Order not found with provided conversion_id or origin_request_id |
Timeout recovery: If querying by origin_request_id returns code 430 = the original order was not recorded on Baokim's side. Merchant can safely retry Create Conversion with the same request_id.
Get Historical Rate
| Code | Message | Description |
|---|
| 404 | Currency Not Supported | Requested foreign currency is not in Merchant's configuration |
| 416 | Invalid Date Range | to_date < from_date, span > 30 days, or to_date > today |