Errors, Logging and Troubleshooting

Before You Start

Read the following guides before proceeding:

Guide	Why
Flutter SDK	Surfaces, isolation model and flows
SDK Setup	Configure options and the credential provider

Where Errors Arrive

Surface	Delivery	Type
Reveal	In the snapshot — `load()` never throws for a request failure	`WirexRevealError { code, retryable }`
Collect	`tokenizeTopUp()` / `tokenizeOctDestination()` throw	`WirexCollectError { code, retryable, reason }`; `reason` is `'cardAlreadyLinked'` or `'cardLimitReached'`
3-D Secure	In the outcome	`WirexThreeDSError`; `code` is `originRefused`, `declined` or `unavailable`
Wallet	`WirexWalletCheckoutFailed` event	`WirexWalletError { kind, code, statusCode, detail }`

WirexDeclined is the one shared sentinel: the user said no and nothing was sent. It is not a
failure.
WirexWalletEnvironmentUnavailable is thrown by WirexWalletEnvironment.resolve for an unknown name.
reason is unknownName, notBuilt or malformedEndpoints. Show the reason; never fall back to another
environment.
An empty chainId on the card surfaces fails configure with an invalid_environment platform error.

bool isRetryable3ds(WirexThreeDSError error) =>
    error.code == WirexThreeDSErrorCode.unavailable && error.retryable;

Future<WirexWalletEnvironment?> safeResolve(String name) async {
  try {
    return await WirexWalletEnvironment.resolve(name);
  } on WirexWalletEnvironmentUnavailable catch (e) {
    showEnvironmentError(e.reason);
    return null;
  }
}

Logging

Logging is off by default. Every logged value passes a redactor.

Surface	Option	Values
Reveal, Collect, 3-D Secure	`logging:` in `configure(...)`	`null` (default), `'debug'`, `'info'`, `'warn'`, `'error'`. Written to the iOS unified log and Android logcat
Wallet	`WirexWalletLogging(level:, sink:)`	Without a sink nothing is written. Default `WirexWalletLogging.disabled`

Log at debug in development builds and warn in release.

Timeouts

Surface	Option	Default
Reveal, Collect	`timeouts: WirexTimeouts(requestMillis:, resourceMillis:)`	15 000 ms request, 30 000 ms resource. `resourceMillis` applies on iOS only
3-D Secure	`pageLoadTimeout: Duration` in `WirexThreeDS.instance.configure(...)`	—

Future<void> configureWithDiagnostics(WirexCredentialProvider credentials) => WirexReveal.instance.configure(
      chainId: '<chain id>',
      credentials: credentials,
      logging: 'info',
      timeouts: const WirexTimeouts(requestMillis: 15000, resourceMillis: 30000),
    );

Troubleshooting

Symptom	Cause	Resolution
`configure` fails with `invalid_environment`	The build has no endpoints for that environment, or `chainId` is empty	Pass `testMode` correctly and a non-empty `chainId`
Reveal or Collect fails with `unauthorized`	Stale bearer. The SDK never retries a `401`	Check expiry and refresh inside `accessToken()`
`401` after the user changed	Identity read at `configure` time	Re-run `configure` with the new identity
API answers `400` on every call	Both `userEmail` and `userWallet` are set	Return exactly one identity
A revealed field is blank	iOS Simulator secure layer, or a box shorter than the row's content	Test on a device; let the row take its natural height
Collect cannot tokenize	Billing details missing, or the user is not enrolled at the acquirer	Send every required billing field — see Collect a Card
The Pay button is unavailable	Availability checker not started, empty provider block, or iOS Simulator	Start `WirexWalletAvailabilityChecker` with the real block; test on a device
3-D Secure ends in `pending`	The payment is not settled yet	Not an error. Settle from the top-up status