Introduction to Wallet API Error Handling
When integrating with Web3 wallet services, understanding error codes is crucial for effective debugging and user experience optimization. This guide provides a detailed breakdown of all error codes returned by the Wallet API, along with troubleshooting recommendations.
👉 Explore OKX's complete Web3 API documentation
Wallet API Error Code Reference Table
Below is the complete list of error codes with their corresponding HTTP status codes and messages:
| Error Code | HTTP Status | Message Description |
|---|---|---|
| 50001 | 200 | Service temporarily unavailable, please retry later |
| 50026 | 500 | System busy, please try again later |
| 81104 | 200 | Blockchain not supported |
| 81105 | 200 | Wallet verification error |
| 81106 | 200 | Address must be lowercase |
| 81107 | 200 | Too many wallet addresses |
| 81108 | 200 | Wallet type mismatch |
| 81109 | 200 | Address update error |
| 81150 | 200 | Chain not supported by this endpoint |
| 81151 | 200 | Invalid token address |
| 81152 | 200 | Token does not exist |
| 81153 | 200 | Platform token detected (no need to add) |
| 81157 | 200 | Blockchain/address mismatch |
| 81158 | 200 | Unsupported token protocol |
| 81159 | 200 | Data caching in progress, please retry |
| 81201 | 200 | Transaction not found |
| 81202 | 200 | Transaction pending confirmation |
| 81203 | 200 | Transaction extjson parameter missing |
| 81302 | 200 | FromAddress doesn't belong to account ID |
| 81351 | 200 | Insufficient balance for payment |
| 81353 | 200 | Invalid address format |
| 81451 | 200 | Node returned failure |
Common Error Categories
Blockchain-Related Errors (81xxx series)
- 81104, 81150: Indicate unsupported blockchain networks
- 81157: Occurs when address format doesn't match the specified chain
Wallet Management Errors
- 81105-81109: Address validation and wallet configuration issues
- 81302: Authorization failures for transaction sources
Token Operation Errors
- 81151-81153, 81158: Token validation and protocol compliance issues
Transaction Processing Errors
- 81201-81203, 81451: Transaction lifecycle and node communication problems
👉 Get started with Wallet API integration
FAQ Section
What should I do when receiving error 50001/50026?
These indicate temporary service interruptions. Implement exponential backoff in your retry logic, waiting 1-5 seconds between attempts.
How to resolve "address must be lowercase" (81106)?
Ensure all address parameters are converted to lowercase before API submission. Most Web3 libraries provide address normalization functions.
What does "node returned failure" (81451) mean?
This suggests the blockchain node couldn't process your request. Verify your transaction parameters are valid for the target network, and consider retrying with adjusted gas parameters.
How to handle "insufficient balance" (81351) errors?
First verify the wallet's native token balance covers both the transaction amount and network fees. For token transfers, remember to account for approval transactions.
Why am I getting "wallet type mismatch" (81108)?
This occurs when attempting operations incompatible with your wallet configuration (e.g., using EOA methods with smart contract wallets). Review the API documentation for wallet-type requirements.
Best Practices for Error Handling
- Implement comprehensive logging of all API responses
- User-friendly messaging that translates technical codes
- Automatic retry logic for temporary failures
- Parameter validation before API submission
- Monitor error rates to detect integration issues
For complete API documentation and additional resources, visit our developer portal.