Wallet API

Error Codes

Copy page

Response Format

All Wallet API responses — including errors — return HTTP 200. The business result is indicated by the code field in the response body.

Code
{
  "code": 0,
  "msg": "success",
  "data": { ... },
  "timestamp": 1718000000000
}

A non-zero code always indicates an error. Check the msg field for a human-readable description.

---

Success

Code	Description
0	Request succeeded

---

Parameter Errors

Code	Message	Cause	Affected Endpoints
40001	Parameter [field] error: <reason>	Request parameter failed validation — field format invalid, value out of range, required parameter missing, or unsupported enum value. The msg field includes the specific field name and reason.	All endpoints

Common 40001 triggers:

• address is blank or missing
• pageSize is out of range (must be 1 ≤ pageSize ≤ 100)
• tokenContractAddresses list in POST /token-balances-by-address contains invalid entries (blank binanceChainId or tokenContractAddress)
• Required @RequestParam or @RequestBody field is absent

---

Authentication & Authorization Errors

These codes are enforced by the API Gateway before the request reaches the Wallet API service.

Code	Message	Cause
40101	Invalid API Key	The X-OC-APIKEY header is missing, malformed, or the key has been deleted / disabled
40102	Signature error	The X-OC-SIGN value does not match the expected HMAC-SHA256 or Ed25519 signature
40103	Timestamp expired	The X-OC-TIMESTAMP is outside the allowed recv_window relative to server time (default ±5 000 ms)
40104	Permission denied	The API Key does not have the required permission for this endpoint

---

Rate Limit Errors

Code	Message	Cause
42900	Request rate limit exceeded. Please refer to the API docs and reduce request frequency	Per-IP, per-API-Key, per-user, or per-endpoint rate limit has been reached. Retry after the duration indicated in the Retry-After response header

---

Compliance Errors

IP Compliance

Code	Message	Cause
40301	Service not available in your region	The client IP originates from a sanctioned jurisdiction (e.g. North Korea, Iran, Cuba, Syria, or OFAC-listed territory)
40302	Proxy or VPN detected. Please use direct connection	A high-risk VPN or proxy was detected on the client connection
40303	Unusual IP activity detected. Please contact support	Anomalous IP activity such as frequent location switching or concurrent multi-region access

---

Server Errors

Code	Message	Cause
50000	Internal server error, please retry later	An unexpected server-side error occurred (e.g. null pointer, serialization error). If the problem persists, contact support with the request timestamp
50001	Service temporarily unavailable, please retry later	An upstream balance data provider is unreachable or returned an error. Retry after a short delay

---

Error Code Reference by Endpoint

Endpoint	Possible Error Codes
GET /api/v1/dex/balance/supported/chain	40001, 50000
GET /api/v1/dex/balance/all-token-balances-by-address	40001, 50000, 50001
POST /api/v1/dex/balance/token-balances-by-address	40001, 50000, 50001
GET /api/v1/dex/post-transaction/transactions-by-address	40001, 50000, 50001
GET /api/v1/dex/post-transaction/transaction-detail-by-txhash	40001, 50000, 50001

---

Troubleshooting Guide

Symptom	Likely Code	Action
Signature mismatch	40102	Verify pre-hash string: timestamp + METHOD + requestPath + body. Ensure requestPath includes the raw query string exactly as sent
Timestamp drift	40103	Sync your system clock with an NTP server. Use X-OC-RECV-WINDOW to extend tolerance (max 60 000 ms)
pageSize out of range	40001	Keep pageSize within [1, 100]
All retries return 50001	50001	The upstream balance service is degraded. Check the status page or contact support