Error Handling

This page collects every sentinel error exposed by the Go SDK, the REST error envelope, and the transient-vs-permanent error classification used by the SDK's polling loops.

REST error envelope

Every non-2xx HTTP response uses the same shape:

{
  "type": "NOT_FOUND",
  "code": "WALLET_NOT_FOUND",
  "message": "The requested resource was not found."
}

type ∈ NOT_FOUND | VALIDATION_ERROR | CONFLICT | INTERNAL_ERROR | ORGANIZATION_NOT_FOUND. The code field provides a machine-readable error code for NOT_FOUND and CONFLICT responses (e.g. CHANNEL_NOT_FOUND, OPERATION_NOT_FINALIZABLE, IDEMPOTENCY_KEY_MISMATCH). See the REST API Reference for the full table.

Transient vs permanent errors

The SDK does not layer automatic HTTP-level retries on top of API calls. Each method on wallets.Client, channels.Client, events.Client, and transact.Client issues its request once and surfaces any error to the caller.

The exception is the watchers.Client polling helpers, WaitForActive and WaitForArchived. These methods poll Get on a time.Ticker (default 2 * time.Second, configurable via crec.WithWatcherPolling). When Get returns a transient error, the loop logs it and continues to the next tick instead of aborting; permanent errors abort the wait immediately.

The transient/permanent classification is implemented in watchers.go (isTransientError / isTransientStatusCode):

For all other sub-clients, retry behaviour is your responsibility. If you wrap calls in your own retry loop, base the transient check on errors.Is(err, …) against the sentinel errors documented below, or on the HTTP status code returned in the REST error envelope.

Common symptoms: what to do

If you're hitting a specific error and just want to know what to fix, find the symptom below first. The full sentinel-error catalog (organised per SDK package) is in the next section.

If the symptom isn't here, look up the exact Err… value in the per-package catalog below.

Sentinel errors by package

All sentinel errors are exported var Err… values. Check with errors.Is(err, pkg.ErrSomething).

crec (root)

apierror (conflict sentinels)

HTTP 409 responses are mapped to canonical sentinels based on ApplicationError.code, so errors.Is works across packages:

An unrecognized or missing code returns no sentinel (forward-compatible for codes added after this SDK release).

channels

events

watchers

wallets

transact

transact/types

transact/eip712

transact/signer/fireblocks

transact/signer/privy

Async error states

Some failures don't surface synchronously: they appear as a state transition on a *.status event:

Subscribe to the appropriate *.status event stream to react to these transitions in real time. See Lifecycles.

Worked example

op, err := ext.PrepareRequestSubscriptionWithTokenApprovalOperation(
    fundAdminAddr, fundTokenId, amount, refID, paymentToken,
)
if err != nil { return fmt.Errorf("build op: %w", err) }

resp, err := client.Transact.ExecuteOperation(ctx, channelID, signer, op, chainSelector)
if err != nil {
    switch {
    case errors.Is(err, transact.ErrChannelNotFound):
        // bad channel id
    case errors.Is(err, eip712.ErrUnsupportedChainFamily):
        // unsupported chain
    default:
        return err
    }
}

See also

• REST API Reference: REST error envelope.
• Lifecycles: async state transitions.
• Event Verification: what events.ErrVerifyEvent actually proves.