6
Error Handling

Proper error handling is critical for a robust payment integration. Here are common errors and how to handle them:

Error Type	Possible Causes	Handling Strategy
Authentication Errors	Invalid credentials Expired token Insufficient permissions	Verify client ID and secret Implement automatic token refresh Contact support for permission issues
Validation Errors	Missing required fields Invalid data format Amount below minimum	Validate data before API calls Display specific error messages Provide guidance on correct formats
Network Errors	Timeout Connection issues API service down	Implement retry with exponential backoff Provide clear error messages to users Have fallback payment options
Payment Processing Errors	Insufficient funds Card declined Fraud detection triggered	Display specific reason to customer Offer alternative payment methods Provide clear next steps

Implementing Robust Error Handling

Error Handling Example

// Example of robust error handling for payment creation
try {
  const checkoutResponse = await createCheckoutSession(paymentData);
  return {
    success: true,
    checkoutUrl: checkoutResponse.checkoutUrl,
    externalId: externalId,
  };
} catch (err) {
  console.error("Payment initiation error:", err);

  let errorMessage = "Failed to process payment request";
  let errorDetails = "";
  let errorType = "UNKNOWN_ERROR";

  if (axios.isAxiosError(err)) {
    // Handle Axios/HTTP errors
    if (err.response) {
      // The server responded with an error status
      const status = err.response.status;
      
      if (status === 401 || status === 403) {
        errorType = "AUTHENTICATION_ERROR";
        errorMessage = "Authentication failed. Please try again.";
      } else if (status === 400) {
        errorType = "VALIDATION_ERROR";
        errorMessage = err.response.data?.message || "Invalid payment information";
      } else if (status >= 500) {
        errorType = "SERVER_ERROR";
        errorMessage = "Payment service is currently unavailable. Please try again later.";
      }
      
      errorDetails = JSON.stringify(err.response.data);
    } else if (err.request) {
      // Request was made but no response received
      errorType = "NETWORK_ERROR";
      errorMessage = "Network Error: No response received from payment server. Please check your connection.";

Security Considerations: Never expose sensitive information like API keys or detailed system errors to end users. Log detailed errors server-side for debugging while providing user-friendly messages on the client side.

Common Error Codes

The SaligPay API uses standard HTTP status codes along with custom error codes in the response body.

HTTP Status	Error Code	Description
400	invalid_request	The request was malformed or missing required parameters
401	unauthorized	Missing or invalid authentication credentials
403	forbidden	Permission denied for the requested operation
404	resource_not_found	The requested resource was not found
409	duplicate_transaction	A payment with the same reference ID already exists
422	validation_error	Request validation failed (invalid amount, currency, etc.)
429	rate_limited	Too many requests, exceeding rate limits
500	server_error	Internal server error occurred

Previous: API Endpoints

Next: Creating a Checkout Session

6Error Handling

Implementing Robust Error Handling

Common Error Codes

6
Error Handling