FundPay Customer Portal

This document provides a comprehensive guide to error codes returned by the FundPay Deposit and Withdrawal APIs. Use this reference to implement proper error handling in your integration.

Quick Reference

Error Code	Type	What It Means	Key Point
1001	Authentication	Invalid API key	✅ Fixed message - API key is invalid
1002	Authentication	Missing API key	✅ Fixed message - API key not provided
1003	Validation	Invalid payload	✅ Fixed message - General payload issue
1005	Authorization	Access denied	✅ Fixed message - Merchant access issue
40001	Client Error	Generic validation error	⚠️ Dynamic message - Check message field for details
50001	Server Error	Generic server error	⚠️ Dynamic message - Check message field for details

🔑 Key Takeaway

Error codes 1001, 1002, 1003, 1005: Have fixed, predictable messages
Error codes 40001, 50001: Are generic codes - always read the message field for specific details

Error Response Format

All API errors follow a consistent JSON structure:

{
  "code": "1001",
  "message": "The provided API key is invalid or expired",
  "data": null
}

Response Fields:

code (string): Unique error code identifier
message (string): Human-readable error description with specific details
data (null|object): Additional error context (typically null)

Understanding Dynamic Error Messages

Some error codes (like 40001 and 50001) are generic codes where the specific error details are provided in the message field. This means the same error code can have different messages depending on the context.

💡 Best Practice: Always parse and log the message field, not just the code. The message contains the specific details you need for debugging.

🔐 Authentication & Authorization Errors (1xxx)

These errors occur when there are issues with API authentication or merchant permissions.

Error Code	HTTP Status	Error Message	Recommended Action
1001	401 Unauthorized	The provided API key is invalid or expired	Verify your API key is correct and active. Contact support if the issue persists.
1002	401 Unauthorized	API key is required but was not provided	Include x-api-key header in your request.
1003	400 Bad Request	The provided payload is invalid	Review the request payload format and ensure all required fields are included.
1005	403 Forbidden	Merchant account not found or inactive	Verify your merchant account is active. Contact support if needed.

⚠️ Request Validation Errors (4xxxx)

These errors indicate problems with the request format or data validation.

40001

Generic Client Error (400 Bad Request)

The error message will contain specific details about what went wrong (e.g., "Invalid request body", "Invalid request: amount must be positive", etc.)

⚠️ Important: Error code 40001 is a generic client error code. The actual error details will be in the message field of the response. Always check the message to understand the specific validation issue.

Common Causes:

Invalid JSON syntax
Missing required fields
Invalid field formats
Business rule violations

🔧 System Errors (5xxxx)

These errors indicate server-side issues. If these persist, contact FundPay support.

50001

Generic Server Error (500 Internal Server Error)

The error message will contain specific details about what operation failed (e.g., "Failed to create deposit", "Failed to create withdrawal", "Failed to generate signature", etc.)

⚠️ Important: Error code 50001 is a generic server error code. The actual error details will be in the message field of the response. These are typically temporary issues that can be resolved by retrying the request.

Recommended Action:

Implement retry logic with exponential backoff. If the issue persists after 3 retries, contact support with:

Error message
Request timestamp
Transaction reference

Error Handling Best Practices

1. Implement Retry Logic

For 5xxxx errors (server errors), implement exponential backoff retry:

async function createDepositWithRetry(payload, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await createDeposit(payload);
      return response;
    } catch (error) {
      if (error.code?.startsWith('5') && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
        await sleep(delay);
        continue;
      }
      throw error;
    }
  }
}

2. Handle Errors by Category

function handleApiError(error) {
  const errorCode = error.code;
  
  // Authentication errors (1xxx)
  if (errorCode === '1001' || errorCode === '1002') {
    console.error('Authentication failed:', error.message);
    return 'Authentication error. Please check your API credentials.';
  }
  
  // Authorization errors
  if (errorCode === '1005') {
    console.error('Access denied:', error.message);
    return 'Access denied. Please contact support.';
  }
  
  // Client errors (40001) - Always check the message
  if (errorCode === '40001') {
    console.error('Validation error:', error.message);
    return `Invalid request: ${error.message}`;
  }
  
  // Server errors (50001) - Implement retry
  if (errorCode === '50001') {
    console.error('Server error:', error.message);
    return 'Service temporarily unavailable. Please try again.';
  }
  
  return 'An unexpected error occurred.';
}

3. Always Log Both Code and Message

Critical: Always log both the error code AND message for debugging:

console.error('API Error:', {
  code: error.code,           // e.g., &quot;40001&quot;
  message: error.message,     // e.g., &quot;Invalid request: amount must be greater than 0&quot;
  endpoint: requestUrl,
  timestamp: new Date().toISOString()
});

Why this matters: Generic error codes like 40001 and 50001 require the message field to understand the actual issue.

API Documentation & Integration Guide

Resources

FundPay API Error Codes Reference