Skip to main content
All SDK errors extend TrussetError and carry a machine-readable code, HTTP statusCode, and the server’s requestId when available. Catch specific subclasses to handle different failure modes.

Error hierarchy

Catching errors

Error properties

Every TrussetError instance exposes:

Common error codes

KYC proof flow codes (NOT_VERIFIED, HASH_MISMATCH, WALLET_MISMATCH, STUB_NOT_ALLOWED, INVALID_MANIFEST, INVALID_HASH, PROOF_REQUIRED, INVALID_CLAIM_TYPE, NO_SELECTED_CLAIMS) are documented with fixes in the KYC proofs troubleshooting table.

Retry behavior

Read requests (GET) are retried on transient failures. Write requests are not - identity writes execute on-chain transactions through the relayer, and blindly repeating an ambiguous failure (5xx, timeout) could submit the same transaction twice. Writes retry only on 429, where the server rejected the request before doing any work.
If an on-chain write fails ambiguously (timeout, 5xx), check identity.getStatus or identity.getClaims before repeating it - the transaction may have landed anyway. Verification and claim writes are safe to repeat: re-verifying updates the identity, re-adding a claim overwrites it.
Retries use exponential backoff: 1s, 2s, 4s, capped at 10s. Configure via maxRetries in the client constructor. Set to 0 to disable.
On-chain write methods enforce higher per-request timeout floors regardless of timeoutMs (180s; addClaimsFromProof 420s), because the backend waits for block confirmations inside the request.

Logging

Pass a logger to surface retry attempts and request metadata during development:
The logger receives debug calls for retry attempts, including the URL and attempt number. No sensitive data (API keys, request bodies) is logged.