Error Codes and Diagnostics

Branch on machine-readable error codes and log normalized diagnostic details. This page identifies each API's result shape; for symptom-first fixes, see Troubleshooting.

Result-based SDK methods

sendIntent(), grantPermissions(), signMessage(), and signTypedData() return structured failure results. sendBatchIntent() is also result-based, but uses flat top-level errorCode / error fields instead of an error.code object — see below.

const result = await client.sendIntent({
  accountAddress,
  targetChain: 8453,
  calls,
})
 
if (!result.success) {
  console.error('1auth request failed', {
    code: result.error?.code,
    message: result.error?.message,
    providerCode: result.error?.details?.providerCode,
    traceId: result.error?.details?.traceId,
    statusCode: result.error?.details?.statusCode,
    errorType: result.error?.details?.errorType,
    simulationUrls: result.error?.details?.simulationUrls,
  })
}

Sponsorship behavior is method-specific:

sendIntent() and grantPermissions() return MISSING_APP_CREDENTIALS or SPONSORSHIP_FETCH_FAILED in result.error.code.
sendBatchIntent() uses top-level errorCode and error. Missing configuration sets error; failed access-token fetches report only through SDK telemetry.
getAssets() rejects for configuration, token-callback, or portfolio failures; use try/catch.

Exception-based integrations

The EIP-1193 provider, viem accounts, and passkey wallet client throw OneAuthError, preserving structured codes and diagnostics.

import { OneAuthError } from '@rhinestone/1auth'
 
try {
  await walletClient.signMessage({ message: 'Approve login' })
} catch (error) {
  if (error instanceof OneAuthError) {
    console.error('1auth request failed', {
      code: error.code,
      message: error.message,
      providerCode: error.details?.providerCode,
      traceId: error.details?.traceId,
      simulationUrls: error.details?.simulationUrls,
    })
  }
}

PayButton converts unsuccessful sendIntent() results to OneAuthError for onError; other failures remain ordinary Error objects, so keep a fallback:

import { OneAuthError, PayButton } from '@rhinestone/1auth/react'
 
<PayButton
  client={client}
  intent={intent}
  onError={(error) => {
    if (error instanceof OneAuthError) {
      console.error(error.code, error.details)
      return
    }
    console.error('Unexpected payment error', error)
  }}
>
  Pay
</PayButton>

Common error codes

Code	Stage	Application behavior
`USER_REJECTED`	Signing dialog	Keep the user on the current screen and allow a new attempt.
`USER_CANCELLED`	Dialog or status wait	Preserve current state; the user deliberately closed the flow.
`PREPARE_FAILED`	Quote or pre-sign simulation	Inspect the returned details. Correct unsupported calldata, balances, or route constraints before retrying. A `No viable route found` message usually means an empty balance, not an unsupported route.
`INVALID_SIGNATURE`	Execution simulation	Start account recovery. Retrying with the same stale passkey will fail again.
`EXECUTE_FAILED`	Submission or execution simulation	Log `providerCode`, `traceId`, and `simulationUrls` for investigation.
`NETWORK_ERROR`	SDK transport	Retry after connectivity recovers.
`SPONSORSHIP_FETCH_FAILED`	App sponsorship	Check the app's access-token or extension-token endpoint.
`HASH_TIMEOUT`	Transaction confirmation	Keep the intent ID and query its status later.
`MISSING_APP_CREDENTIALS`	Client configuration	Configure SDK sponsorship credentials before sponsored operations or asset queries.
`INVALID_OPTIONS`	Client validation	Correct the request before opening another dialog.

Diagnostic fields

Field	Purpose
`providerCode`	Machine-readable code returned by the Rhinestone provider.
`traceId`	Correlation ID to include in logs and support requests.
`statusCode`	Upstream HTTP status, when available.
`errorType`	Orchestrator execution-error category.
`simulationUrls`	Links to available transaction simulation traces.

Use these only in developer logs and support tooling. Never render raw simulation URLs or provider diagnostics to users.