Error Handling
Learn how to properly handle errors and exceptions from the SDK to provide a smooth user experience.
Overview
The SDK uses a combination of exception classes and callback parameters to communicate errors. Understanding these patterns helps you build robust error handling.
EdfaException
SDK-specific errors with error codes
onError Callback
General error callback for all operations
Response Codes
Transaction-specific response codes
Timeout Callbacks
Specific callbacks for timeout scenarios
EdfaException
The SDK throws EdfaException for SDK-specific errors:
Loading...EdfaError Hierarchy
The modern, type-safe error hierarchy used by the SDK. It uses a Kotlin sealed class structure organized by category, making it easier to parse specific errors exhaustively.
Initialization (1xxx)
| Error Type | Code | Description |
|---|---|---|
| Initialization.PluginNotInitialized | 1001 | Plugin not initialized properly |
| Initialization.SdkNotInitialized | 1002 | SDK not initialized |
| Initialization.SessionFailed | 1003 | Session creation failed |
| Initialization.ConfigurationMissing | 1004 | Terminal configuration missing |
| Initialization.ConfigurationInitFailed | 1005 | Configuration init failed |
| Initialization.UnsupportedSdkVersion | 1006 | Unsupported SDK version on device |
Network (2xxx)
| Error Type | Code | Description |
|---|---|---|
| Network.Timeout | 2001 | HTTP request timeout |
| Network.ServerUrlInvalid | 2002 | Invalid server URL |
| Network.EnvironmentUndefined | 2003 | Environment not defined |
| Network.NonceFailure | 2004 | Nonce generation failed |
| Network.ServerKeyFailure | 2005 | Server key error |
| Network.TransactionProcessingFailure | 2006 | Transaction processing failed |
| Network.NullResponse | 2007 | Null response from server |
| Network.GeneralServerError | 2008 | General server error |
Card (3xxx)
| Error Type | Code | Description |
|---|---|---|
| Card.NotSupported | 3001 | Card scheme not supported |
| Card.InvalidOrNotSupported | 3002 | Invalid or unsupported card |
| Card.DisconnectedWhileProcessing | 3003 | Card disconnected during processing |
| Card.AppletNotSelected | 3004 | Applet not selected |
| Card.TlvDecodingError | 3005 | TLV decoding error |
| Card.TlvDecodedNull | 3006 | TLV decoded to null |
| Card.ProcessingAidError | 3007 | AID processing error |
| Card.NoNfcTransceiver | 3008 | No NFC transceiver |
Kernel (4xxx)
| Error Type | Code | Description |
|---|---|---|
| Kernel.NotImplemented | 4001 | Kernel not implemented |
| Kernel.VisaNotInitialized | 4002 | Visa kernel not initialized |
| Kernel.MastercardNotInitialized | 4003 | Mastercard kernel not initialized |
| Kernel.AmexNotInitialized | 4004 | Amex kernel not initialized |
| Kernel.DiscoverNotInitialized | 4005 | Discover kernel not initialized |
| Kernel.AlcineoNotInitialized | 4006 | Alcineo kernel not initialized |
Terminal (5xxx)
| Error Type | Code | Description |
|---|---|---|
| Terminal.PreparationFailed | 5001 | Terminal preparation failed |
| Terminal.RegistrationFailed | 5002 | Terminal registration failed |
| Terminal.TsnNotFound | 5003 | TSN not found |
| Terminal.CounterFailed | 5004 | Transaction counter failed |
| Terminal.InvalidMerchantId | 5005 | Invalid merchant ID in auth code |
Transaction (6xxx)
| Error Type | Code | Description |
|---|---|---|
| Transaction.InvalidParams | 6001 | Invalid transaction params |
| Transaction.MissingProcessingCode | 6002 | Missing processing code |
| Transaction.MissingLastApproved | 6003 | Missing last approved transaction |
| Transaction.NotLastTransaction | 6004 | Not the last transaction |
| Transaction.NotExistToReverse | 6005 | Transaction doesn't exist to reverse |
| Transaction.MissingIdOrRrn | 6006 | Missing transaction ID or RRN |
| Transaction.MissingData | 6007 | Missing transaction data |
Authentication & Validation
| Error Type | Code | Description |
|---|---|---|
| Authentication.Failed | 7001 | Authentication failed |
| Authentication.LocationNotGranted | 7002 | Location permission not granted |
| Validation.PinLengthInvalid | 8001 | Invalid PIN length configuration |
| Validation.EnvValueUpdateFailed | 8002 | Environment value update failed |
Security & Generic
| Error Type | Code | Description |
|---|---|---|
| Security.EncryptionFailed | 9001 | Encryption failed |
| Generic.SomethingWentWrong | 1 | Generic error |
| Generic.NullDataOnSuccess | 2 | Null data on success callback |
| Generic.Custom | -1 | Custom error with message |
Creating Custom Errors
You can easily map native throwables into custom EdfaErrors or vice-versa.
Loading...Error Handling Pattern
Implement comprehensive error handling using type checking:
Loading...Transaction Response Handling
Handle different transaction outcomes:
Loading...Common Errors
| Error | Cause | Resolution |
|---|---|---|
| SESSION_EXPIRED | Authentication token expired | Re-initialize SDK with fresh credentials |
| INVALID_CREDENTIALS | Wrong auth token or credentials | Verify credentials and retry |
| TERMINAL_NOT_ACTIVE | Terminal not activated | Call activateTerminal() |
| NFC_NOT_AVAILABLE | Device lacks NFC or disabled | Prompt user to enable NFC |
| LOCATION_REQUIRED | Location permission denied | Request location permission |
| NETWORK_ERROR | No internet connection | Check connectivity and retry |
| CARD_READ_ERROR | Failed to read card | Ask user to retry tap |
| TRANSACTION_DECLINED | Issuer declined transaction | Show decline reason to user |
Debug Logging
Enable debug logging during development to see detailed error information:
EdfaPayPlugin.enableLogs = true
Filter logcat with tag: ***EdfaPay***
On this page
Downloads
Coming SoonSample apps, release bundles, and more content will be available here soon.