IMPLEMENTATION GUIDE
Errors & troubleshooting
Check connectivity, authentication, execution conditions and on-chain results in order. Before resubmitting, establish whether the previous request was accepted.
Diagnose by symptom
| Symptom | What to check |
|---|---|
| ERR_MODULE_NOT_FOUND | Run node in the directory where dependencies were installed. Check the package version includes @hazbase/kit/wallet. |
| Timeout / fetch failed | Check endpoint, network, proxy and certificate. For browser-only failures, check Origin/CORS. |
| 401 / 403 | Check authentication, expiry, origin, device and policy. These are general HTTP categories; consult response codes for the specific operation. |
| 404 | Check for confusion between HTTP API and RPC. Verify API version and path. |
| 429 | Check response headers and provider limits. For writes, establish acceptance before retrying. |
| Zero tokens | Connectivity and token configuration are separate. Check chain ID and configured tokens. |
| Write failure | Check roles, balance, transfer conditions, pause status, approvals and expiry. |
Inspect SDK errors
error-handling.mjs
import { HazbaseWalletApiError } from "@hazbase/kit/wallet";
export function describeError(error) {
if (error instanceof HazbaseWalletApiError) {
return { status: error.status, code: error.code, message: error.message };
}
return { message: error instanceof Error ? error.message : String(error) };
}Information to share with support
Provide SDK version, API path, time, HTTP status, code, request ID and reproduction steps. Do not share private keys, OTPs, access tokens or high-trust tokens.