Error Codes and Diagnostics

1auth exposes structured errors and provider diagnostics across signing and intent flows, with method-specific result shapes described below. Branch on a machine-readable error.code when the method supplies one, and log normalized error.details while integrating.

This page is the reference for the codes themselves. For symptom-first fixes — "the prompt never appears", "the address changed" — 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 failures are method-specific:

• sendIntent() returns MISSING_APP_CREDENTIALS or SPONSORSHIP_FETCH_FAILED in result.error.code.
• grantPermissions() returns the same two codes in its structured result.
• sendBatchIntent() reports top-level failures through its own errorCode and error fields rather than a nested error.code. Missing sponsorship configuration sets error; a failed access-token fetch sets neither and reports only through SDK telemetry. See Troubleshooting for the full list.
• getAssets() rejects with an Error for missing configuration, token callback failures, or portfolio request failures; use try/catch.

Exception-based integrations

The EIP-1193 provider, viem accounts, and the passkey wallet client use exception-based APIs. They throw OneAuthError, which preserves the structured code and diagnostic details.

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 an unsuccessful structured sendIntent() result into a OneAuthError before calling onError. Other exceptions caught while authenticating or sending are forwarded as ordinary Error objects, so retain a generic 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

Diagnostic fields

These fields are intended for developer logs and support tooling. Do not render raw simulation URLs or provider diagnostics as user-facing error messages.