Trusset Protocol - Infrastructure for Asset Tokenization

This page is for the engineer writing the catch blocks. After reading it you will know which errors are worth retrying, which are not, and why an ambiguous write failure needs a status check rather than a retry. 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

import {
  TrussetError,
  AuthError,
  ValidationError,
  NetworkError,
} from '@trusset/sdk'

ValidationError is the one that never reaches the network. The SDK raises it from client-side checks, so it costs no request and its message names the offending field.

Class	Status	Fires when	Do
`ValidationError`	400	Input rejected before hitting the API	Fix the input. Retrying is pointless.
`AuthError`	401	API key is invalid, expired, or the instance is archived	Check the key and the instance state.
`NetworkError`	0	Timeout, DNS failure, connection refused	Retry a read. For a write, check status first.
`TrussetError`	4xx / 5xx	Server returned a non-success response	Branch on `code`.

Order the branches from most specific to least. TrussetError is the base class, so a leading instanceof TrussetError swallows every other case.

Catch errors

try {
  await trusset.customers.manage.get('0xinvalid')
} catch (err) {
  if (err instanceof ValidationError) {
    console.error(err.message)
    return
  }

  if (err instanceof AuthError) {
    console.error(err.message, err.requestId)
    return
  }

  if (err instanceof NetworkError) {
    console.error(err.message)
    return
  }

  if (err instanceof TrussetError) {
    console.error(err.code, err.statusCode, err.message, err.requestId)
  }
}

The ValidationError from that call reports walletAddress must be a valid Ethereum address.

Error properties

Every TrussetError instance exposes:

Property	Type	Description
`message`	`string`	Human-readable error description
`code`	`string`	Machine-readable error code (e.g. `NOT_FOUND`, `TX_REVERTED`)
`statusCode`	`number`	HTTP status code. `0` for network errors.
`requestId`	`string \| null`	Server-assigned request ID for support inquiries

Common error codes

Code	Status	Meaning
`AUTH_REQUIRED`	401	No API key provided
`AUTH_FAILED`	401	Invalid or expired API key
`NOT_FOUND`	404	Resource does not exist
`CUSTOMER_EXISTS`	409	Duplicate wallet or externalId
`WALLET_IN_USE`	409	Wallet already assigned to another customer
`SERVICE_NOT_ENABLED`	403	Required service not enabled on this instance
`RELAYER_NOT_CONFIGURED`	400	No verified wallet is registered on this instance
`TX_NOT_FOUND`	404	The transaction being confirmed has no receipt yet
`TX_REVERTED`	400	The transaction being confirmed reverted on-chain
`VALIDATION_ERROR`	400	Client-side input validation failure

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 carry on-chain side effects, 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.

Status	GET	POST / PUT / DELETE
408 Request Timeout	Retried	No
429 Too Many Requests	Retried	Retried
500 / 502 / 503 / 504	Retried	No
Network errors (DNS, connection)	Retried	No
Timeouts (AbortError)	Retried	No
400, 401, 403, 404, 409	No	No

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.

const trusset = new TrussetClient({
  apiKey: '...',
  maxRetries: 5,
  timeoutMs: 60_000,
})

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.

Enable logging

Pass a logger to surface retry attempts and request metadata during development:

const trusset = new TrussetClient({
  apiKey: '...',
  logger: console,
})

The logger receives debug calls for retry attempts, including the URL and attempt number. No sensitive data (API keys, request bodies) is logged.

Getting Started

Customers

Error Handling

Error hierarchy

Catch errors

Error properties

Common error codes

Retry behavior

Enable logging

​Error hierarchy

​Catch errors

​Error properties

​Common error codes

​Retry behavior

​Enable logging

Error hierarchy

Catch errors

Error properties

Common error codes

Retry behavior

Enable logging