Error Handling

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:

{
  code: string,           // Error code for programmatic handling
  message: string,        // Human-readable error message
  severity: string,       // 'info' | 'warning' | 'error' | 'critical'
  recoverable: boolean,   // Whether the error can be recovered from
  suggestedAction?: string, // Recommended recovery action
  fieldErrors?: Array,    // Field-specific validation errors
  context?: object       // Additional error context
}

Error Types

Validation Errors

These occur when form fields contain invalid data:

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:

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:

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 the NekudaWalletProvider:

onValidationError

Called when field validation fails. Receives an array of field-specific errors.

<NekudaWalletProvider
  publicKey="pk_test_..."
  userId="user_123"
  onValidationError={(fieldErrors) => {
    // fieldErrors: Array of { fieldName, message, fieldType }
    const errorMessages = fieldErrors.map(e => e.message).join(', ');
    setFormError(errorMessages);
  }}
>

onError

Called for all other errors (network, API, configuration).

<NekudaWalletProvider
  publicKey="pk_test_..."
  userId="user_123"
  onError={(error) => {
    // error: { code, message, severity, recoverable, suggestedAction }
    if (error.recoverable) {
      // Can retry the operation
      handleRetry();
    } else {
      // Show error to user
      showErrorNotification(error.message);
    }
  }}
>

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

Show Recovery Example

function PaymentFormWithRecovery() {
  const [retryCount, setRetryCount] = useState(0);
  const maxRetries = 3;

  const handleError = (error) => {
    if (error.suggestedAction === 'retry' && retryCount < maxRetries) {
      const delay = Math.pow(2, retryCount) * 1000; // Exponential backoff
      setTimeout(() => {
        setRetryCount(retryCount + 1);
        // Retry the operation
      }, delay);
    } else {
      // Show final error
      console.error('Failed after retries:', error.message);
    }
  };

  return (
    <NekudaWalletProvider
      onError={handleError}
      publicKey="pk_test_..."
      userId="user_123"
    >
      <NekudaPaymentForm />
    </NekudaWalletProvider>
  );
}

Common Error Scenarios

Invalid Card Number

// Error received in onValidationError
{
  fieldName: "cardNumber",
  fieldType: "cardNumber",
  message: "Please enter a valid card number"
}

Expired Card

// Error received in onValidationError
{
  fieldName: "cardExpiry",
  fieldType: "cardExpiry", 
  message: "Card has expired"
}

Rate Limited

// Error received in onError
{
  code: "API_RATE_LIMITED",
  message: "Too many requests. Please wait before trying again.",
  severity: "warning",
  recoverable: true,
  suggestedAction: "retry"
}

Network Timeout

// Error received in onError
{
  code: "NETWORK_TIMEOUT",
  message: "Request timed out. Please try again.",
  severity: "warning",
  recoverable: true,
  suggestedAction: "retry"
}

Best Practices

Always Set Both Error Handlers

Configure both onValidationError and onError on your provider to catch all error types.

Check Error Severity

Handle errors based on severity - critical errors may require page reload, while warnings can be retried.

Use Suggested Actions

Follow the suggestedAction field when present for appropriate error recovery.

Provide User Feedback

Always inform users when errors occur with clear, actionable messages.

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

For additional support, contact our support team with the error code and message.

Get Started

Frontend SDK

Backend SDK

Security

Testing

Overview

Error Structure

Error Types

Validation Errors

Network Errors

API Errors

Error Callbacks

onValidationError

onError

Error Recovery

Common Error Scenarios

Invalid Card Number

Expired Card

Rate Limited

Network Timeout

Best Practices

Troubleshooting

Payment Form Not Loading

Validation Errors Not Showing

Network Errors

Get Started

Frontend SDK

Backend SDK

Security

Testing

​Overview

​Error Structure

​Error Types

​Validation Errors

​Network Errors

​API Errors

​Error Callbacks

​onValidationError

​onError

​Error Recovery

​Common Error Scenarios

​Invalid Card Number

​Expired Card

​Rate Limited

​Network Timeout

​Best Practices

​Troubleshooting

​Payment Form Not Loading

​Validation Errors Not Showing

​Network Errors

Overview

Error Structure

Error Types

Validation Errors

Network Errors

API Errors

Error Callbacks

onValidationError

onError

Error Recovery

Common Error Scenarios

Invalid Card Number

Expired Card

Rate Limited

Network Timeout

Best Practices

Troubleshooting

Payment Form Not Loading

Validation Errors Not Showing

Network Errors