Overview
The nekuda SDK provides comprehensive error handling with specific error types, severity levels, and recovery suggestions. All errors follow a consistent structure to help you handle them appropriately.Error Structure
Every error in the SDK contains the following information:Error Types
Validation Errors
These occur when form fields contain invalid data:- Error Codes
- Example Handling
Code | Description | Severity |
---|---|---|
VALIDATION_REQUIRED | Required field is empty | Error |
VALIDATION_INVALID | Field value is invalid | Error |
VALIDATION_EXPIRED | Card has expired | Error |
VALIDATION_FORMAT | Incorrect format (e.g., card number) | Error |
VALIDATION_LENGTH | Value too short or too long | Error |
Network Errors
These occur when there are connectivity issues:- Error Codes
- Example Handling
Code | Description | Severity | Recoverable |
---|---|---|---|
NETWORK_TIMEOUT | Request timed out | Warning | Yes |
NETWORK_OFFLINE | No internet connection | Error | No |
NETWORK_CONNECTION_LOST | Connection lost during operation | Warning | Yes |
API Errors
These occur when the nekuda service returns an error:- Error Codes
- Example Handling
Code | Description | Severity | Action |
---|---|---|---|
API_UNAUTHORIZED | Invalid or expired API key | Critical | Check public key |
API_FORBIDDEN | Access denied | Critical | Verify permissions |
API_RATE_LIMITED | Too many requests | Warning | Retry after delay |
API_BAD_REQUEST | Invalid request data | Error | Check input |
API_SERVER_ERROR | Server error | Error | Contact support |
Error Callbacks
The SDK provides two main error callbacks on theNekudaWalletProvider
:
onValidationError
Called when field validation fails. Receives an array of field-specific errors.onError
Called for all other errors (network, API, configuration).Error Recovery
The SDK provides suggested actions for different error types:Suggested Action | When Used | Example Implementation |
---|---|---|
retry | Network timeouts, rate limits | Retry after delay |
check_input | Validation errors | Highlight invalid fields |
reauthenticate | Auth errors | Refresh API key |
contact_support | Server errors | Show support contact |
refresh | Iframe issues | Reload the page |
Common Error Scenarios
Invalid Card Number
Expired Card
Rate Limited
Network Timeout
Best Practices
1
Always Set Both Error Handlers
Configure both
onValidationError
and onError
on your provider to catch all error types.2
Check Error Severity
Handle errors based on severity - critical errors may require page reload, while warnings can be retried.
3
Use Suggested Actions
Follow the
suggestedAction
field when present for appropriate error recovery.4
Provide User Feedback
Always inform users when errors occur with clear, actionable messages.
5
Log Errors
Log errors to your monitoring service for debugging and improving user experience.
Troubleshooting
Payment Form Not Loading
If the payment form doesn’t appear:- Check browser console for error messages
- Verify your public key is correct
- Ensure nekuda domains aren’t blocked by CSP or firewall
Validation Errors Not Showing
If validation errors aren’t displayed:- Ensure you’ve implemented the
onValidationError
callback - Check that field error messages are being rendered in your UI
Network Errors
For persistent network errors:- Check internet connectivity
- Verify nekuda services are accessible
- Check for proxy or VPN interference