Error handling

All SDK calls throw EkycError on failure. Catch and inspect:

try {
  final r = await sdk.liveness.check(/* ... */);
} on EkycError catch (e) {
  print('ekyc: ${e.code} (request_id=${e.requestId}): ${e.message}');
}

Fields

Field	Type	Notes
code	String	Maps to error.type in the wire envelope
message	String	Human-readable summary
statusCode	int?	HTTP status; null for pre-flight errors
requestId	String?	The gateway's request_id. Quote in support tickets.
param	String?	For validation_failed, names the offending field
docUrl	String?	Link to a docs page documenting the error
retryAfter	Duration?	For rate_limited, how long to wait
cause	Object?	Wrapped underlying exception (network errors)

Sentinel constants

EkycErrorCode.* exposes the strings:

import 'package:ekyc_sdk/ekyc_sdk.dart' show EkycErrorCode;

// EkycErrorCode.tokenExpired         == 'token_expired'
// EkycErrorCode.invalidCredentials   == 'invalid_credentials'
// EkycErrorCode.rateLimited          == 'rate_limited'
// EkycErrorCode.validationFailed     == 'validation_failed'
// EkycErrorCode.networkError         == 'network_error'
// EkycErrorCode.tokenProviderFailed  == 'token_provider_failed'
// EkycErrorCode.cameraPermissionRequired == 'camera_permission_required'

See Errors and retries for the full list.

tokenProvider failures

If your tokenProvider callback throws (e.g. your backend is down), the SDK wraps the underlying exception:

final sdk = EkycSdk(EkycConfig(
  tokenProvider: () async {
    throw Exception('backend unreachable');
  },
));

try {
  await sdk.sessions.create(customerRef: 'x');
} on EkycError catch (e) {
  e.code        // 'token_provider_failed'
  e.cause       // Exception: backend unreachable
}

The SDK does not retry your tokenProvider. That's your responsibility — add retry logic, circuit breakers, etc. inside the callback.