> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rinne.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and Debugging

> Handle SDK errors consistently and troubleshoot wallet, card, and 3DS integrations.

This page explains how to handle runtime and integration errors across wallet, card, and 3DS components.

Use these patterns to show clear user messages, keep checkout recoverable, and capture diagnostics for backend and support teams.

## Wallet Error Handling

Wallet elements expose `onError` and `onCancel` handlers.

```typescript theme={null}
onError: (error) => {
  console.error('Wallet error', error.code, error.message)
},
onCancel: () => {
  console.log('User cancelled wallet flow')
}
```

Possible error codes:

* `PROVIDER_ERROR`
* `VALIDATION_ERROR`
* `CONFIGURATION_ERROR`
* `UNKNOWN`

## Card and 3DS Mount Errors

`mount()` throws if the target is invalid or if the provider component fails to mount.

```typescript theme={null}
try {
  const card = await rinne.elements.card()
  await card.mount('#missing-container')
} catch (error) {
  console.error('Mount failed:', error)
}
```

```typescript theme={null}
try {
  const threeDSecure = await rinne.elements.threeDSecure()
  await threeDSecure.mount('')
} catch (error) {
  console.error('3DS mount failed:', error)
}
```

## Common Failure Points

<AccordionGroup>
  <Accordion title="Target element not found">
    The selector passed to `mount()` does not match a DOM node. Ensure the element exists before mounting.
  </Accordion>

  <Accordion title="Wallet buttons not rendering">
    Check HTTPS, browser/device compatibility, and Apple Pay domain verification.
  </Accordion>

  <Accordion title="Wallet dialog stuck after authorization">
    Your `onCapture` handler likely failed without calling `fail()`. Always call `fail()` when backend charge creation fails.
  </Accordion>

  <Accordion title="3DS session errors">
    Verify that sessions are not expired. Sessions expire 1 hour after creation. Request a new session and remount on retry.
  </Accordion>

  <Accordion title="3DS proceeds despite FAILED auth_status">
    Always check `auth_status` from your backend session response before mounting the 3DS element. A `FAILED` status means the card was rejected before the authentication flow could start — do not mount and do not proceed with payment. Only mount for `ACTION_REQUIRED`; the SDK handles frictionless and challenge flows internally from there.
  </Accordion>
</AccordionGroup>

## Debug Logging Pattern

```typescript theme={null}
const log = (event: string, payload?: unknown) => {
  console.log(`[rinne-checkout] ${event}`, payload)
}

const walletHandlers = {
  onCapture: async (payload, fail) => {
    log('wallet.capture', payload)
    try {
      await charge(payload)
      log('wallet.capture.success')
    } catch (error) {
      log('wallet.capture.failure', error)
      fail({ message: error instanceof Error ? error.message : 'Charge failed' })
    }
  },
  onError: (error) => log('wallet.error', error),
  onCancel: () => log('wallet.cancel')
}
```