Error Handling
Understanding and handling API errors
All API errors return a consistent JSON structure with an error code and message.
Error Response Format
{
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "Wallet has insufficient available balance for this operation"
}
}Common Error Codes
| Code | HTTP Status | Description |
|---|---|---|
INSUFFICIENT_BALANCE | 400 | Not enough available funds |
WALLET_NOT_FOUND | 404 | Wallet does not exist |
WALLET_FROZEN | 403 | Wallet is frozen |
RESERVATION_EXPIRED | 400 | Reservation has expired |
IDEMPOTENCY_CONFLICT | 409 | Different request with same idempotency key |
POLICY_VIOLATION | 400 | Operation violates policy rules |
Handling Errors
Always check for both HTTP status codes and error codes in your integration.