Error Handling
Learn how to properly handle errors and exceptions from the SDK to provide a smooth user experience.
Overview
The EdfaPay SDK uses a sealed class hierarchy (EdfaError) and typed exception (EdfaException) to provide structured, actionable error information.
EdfaException
Typed exception thrown in catch blocks
EdfaError
Sealed class hierarchy for structured errors
Response Codes
Server response codes for transaction results
Custom Errors
Plugin-level error categories
EdfaException
The SDK throws EdfaException for SDK-specific errors. It wraps an EdfaError with a typed error category and optional cause.
| Property | Type | Description |
|---|---|---|
| error | EdfaError | The typed error object with code and message |
| message | String? | Human-readable error description |
| cause | Throwable? | Underlying cause, if available |
EdfaError Hierarchy
The modern, type-safe error hierarchy used by the SDK. Each subtype carries a numeric code in a specific range.
| EdfaError Subtype | Code Range | Category |
|---|---|---|
| EdfaError.InitializationError | 1xxx | SDK setup and auth failures |
| EdfaError.NetworkError | 2xxx | Connectivity and server communication issues |
| EdfaError.CardError | 3xxx | Card reading and NFC issues |
| EdfaError.KernelError | 4xxx | EMV kernel processing failures |
| EdfaError.TerminalError | 5xxx | Terminal configuration and binding problems |
| EdfaError.TransactionError | 6xxx | Transaction processing failures |
| EdfaError.AuthenticationError | 7xxx | Auth token or credential issues |
| EdfaError.ValidationError | 8xxx | Input/parameter validation failures |
| EdfaError.SecurityError | 9xxx | Security policy violations |
Error Handling Pattern
Use when-expression (Kotlin) or instanceof (Java) to handle each error category precisely.
Loading...Debug Logging
Enable debug logging during development: EdfaPayPlugin.enableLogs(true)
Transaction Response Handling
Handle different transaction outcomes using the TxnResponse callback.
Loading...Common Errors
Frequently encountered error codes with causes and resolution guidance.
| Code | Category | Meaning | Resolution |
|---|---|---|---|
| 1001 | Initialization | Invalid auth credentials | Check your authToken or email/password |
| 1002 | Initialization | SDK not initialized | Call EdfaPayPlugin.initiate() first |
| 1003 | Initialization | No terminal bound | Complete terminal binding in onTerminalBindingTask |
| 2001 | Network | Network connection timeout | Check device internet/network connection |
| 2002 | Network | Server unreachable | Verify API endpoint and network access |
| 3001 | Card | Card read timeout | Ask user to tap card again within timeout window |
| 3002 | Card | Unsupported card type | Only NFC-capable payment cards supported |
| 3003 | Card | Card communication error | Clean card/device NFC area and retry |
| 4001 | Kernel | EMV processing failure | Sync terminal to update EMV parameters |
| 5001 | Terminal | Terminal not activated | Call activateTerminal() first |
| 5002 | Terminal | Terminal binding required | Select terminal in onTerminalBindingTask callback |
| 6001 | Transaction | Transaction declined | Card declined by issuer — do not retry |
| 6002 | Transaction | Insufficient funds | Customer should use different card |
| 6003 | Transaction | Transaction already reversed | Cannot reverse same transaction twice |
| 7001 | Authentication | Session expired | Call initiate() again to create new session |
| 9001 | Security | Location validation failed | Enable real device location, disable mock locations |
| 9002 | Security | Certificate pinning failure | Check certificate validity and network proxy |
On this page
Downloads
Coming SoonSample apps, release bundles, and more content will be available here soon.