Skip to main content

​
Error Response Structure

When an API request fails, the response will have success set to "false" (string) and include an error object with details.

​
Error Object

​
error
object
Contains error information

​
Example Error Response

{
  "error": {
    "message": "An error occurred while we were processing your request",
    "code": "internal_server_error"
  },
  "success": "false"
}

​
Common Error Codes

​
Authentication Errors

Cause: Invalid or missing API keySolution:
  • Verify your API key is correct
  • Ensure the API-KEY header is included in the request
  • Check you’re using the right key for the environment (sandbox vs production)
{
  "error": {
    "message": "Invalid or missing API key",
    "code": "authentication_error"
  },
  "success": "false"
}

​
Transaction Errors

Cause: Merchant account doesn’t have enough balance for the transactionSolution:
  • Check your balance using the /api/agent_balance endpoint
  • Add funds to your merchant account
  • Reduce the transfer amount
{
  "error": {
    "message": "Insufficient funds in merchant account",
    "code": "insufficient_funds"
  },
  "success": "false"
}
Cause: Phone number format is incorrectSolution:
  • Use E.164 format without the + sign
  • Format: [country code][subscriber number]
  • Example: 16175551212 for a US number
{
  "error": {
    "message": "Invalid phone number format",
    "code": "invalid_phone_number"
  },
  "success": "false"
}
Cause: The specified transfer ID doesn’t existSolution:
  • Verify the transfer ID is correct
  • Check if the transfer was created in the same environment
  • Ensure you’re using the ID returned from the transfer creation
{
  "error": {
    "message": "Transfer not found",
    "code": "transfer_not_found"
  },
  "success": "false"
}
Cause: Recipient account is not KYC verified and cannot receive the transfer amountSolution:
  • Check KYC status using /api/kyc/:account endpoint
  • Direct user to complete KYC verification via the kyc_url provided
  • Reduce transfer amount to within the unverified limit
{
  "error": {
    "message": "Recipient KYC verification required",
    "code": "kyc_not_verified"
  },
  "success": "false"
}

​
Server Errors

Cause: An unexpected error occurred on the serverSolution:
  • Retry the request after a brief delay
  • If the error persists, contact support
  • Check the CashQ status page for any ongoing issues
{
  "error": {
    "message": "An error occurred while we were processing your request",
    "code": "internal_server_error"
  },
  "success": "false"
}
Cause: The API service is temporarily unavailableSolution:
  • Implement retry logic with exponential backoff
  • Wait and retry the request
  • Contact support if the issue persists

​
Validation Errors

Cause: Request parameters are missing or invalidSolution:
  • Review the endpoint documentation
  • Verify all required parameters are included
  • Check parameter types and formats
  • Ensure JSON is properly formatted
{
  "error": {
    "message": "Invalid request parameters",
    "code": "invalid_request"
  },
  "success": "false"
}
Cause: Transfer amount is invalid (negative, zero, or exceeds limits)Solution:
  • Ensure amount is a positive number
  • Check minimum and maximum transfer limits
  • Verify amount format (string with decimal)

​
Error Handling Best Practices

​
1. Always Check Success Field

const response = await fetch(url, options);
const data = await response.json();

if (data.success !== true && data.success !== 'true') {
  // Handle error
  handleError(data.error);
} else {
  // Process successful response
  processData(data);
}

​
2. Implement Retry Logic

For transient errors like internal_server_error, implement retry with exponential backoff: 
async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      const data = await response.json();
      
      if (data.success === true || data.success === 'true') {
        return data;
      }
      
      // Don't retry for client errors
      if (data.error.code === 'authentication_error' || 
          data.error.code === 'invalid_request') {
        throw new Error(data.error.message);
      }
      
      // Retry for server errors
      if (i < maxRetries - 1) {
        await new Promise(resolve => 
          setTimeout(resolve, Math.pow(2, i) * 1000)
        );
      }
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

​
3. Use Error Codes for Logic

function handleError(error) {
  switch (error.code) {
    case 'authentication_error':
      // Redirect to login or refresh credentials
      redirectToLogin();
      break;
      
    case 'insufficient_funds':
      // Show balance warning to user
      showInsufficientFundsWarning();
      break;
      
    case 'kyc_not_verified':
      // Direct user to KYC verification
      redirectToKYC(error.kyc_url);
      break;
      
    case 'internal_server_error':
      // Retry the request
      retryRequest();
      break;
      
    default:
      // Show generic error message
      showErrorMessage(error.message);
  }
}

​
4. Log Errors for Debugging

function logError(endpoint, error, requestData) {
  console.error('API Error:', {
    timestamp: new Date().toISOString(),
    endpoint: endpoint,
    errorCode: error.code,
    errorMessage: error.message,
    requestData: requestData
  });
  
  // Send to your logging service
  sendToLoggingService({
    level: 'error',
    endpoint: endpoint,
    error: error,
    request: requestData
  });
}

​
5. Provide User-Friendly Messages

Don’t show raw error messages to users. Translate error codes into user-friendly messages: 
const userFriendlyMessages = {
  'authentication_error': 'Unable to authenticate. Please check your credentials.',
  'insufficient_funds': 'Insufficient balance. Please add funds to your account.',
  'invalid_phone_number': 'Please enter a valid phone number.',
  'kyc_not_verified': 'Recipient needs to complete verification to receive this amount.',
  'internal_server_error': 'Something went wrong. Please try again.',
  'transfer_not_found': 'Transfer not found. Please check the transfer ID.'
};

function getUserMessage(errorCode) {
  return userFriendlyMessages[errorCode] || 'An error occurred. Please try again.';
}

​
HTTP Status Codes

In addition to the error object in the response body, check HTTP status codes:
Status CodeMeaningAction
200OKCheck success field in response body
400Bad RequestFix request parameters
401UnauthorizedCheck API key
404Not FoundVerify endpoint URL
429Too Many RequestsImplement rate limiting
500Internal Server ErrorRetry with backoff
503Service UnavailableRetry later

​
Error Handling Checklist

Before deploying to production, ensure you have:
  • Checked the success field in all API responses
  • Implemented retry logic for transient errors
  • Used error codes for programmatic handling
  • Logged errors for debugging and monitoring
  • Provided user-friendly error messages
  • Handled authentication errors appropriately
  • Tested error scenarios in sandbox
  • Set up monitoring and alerting for errors

​
Need Help?

Contact Support

Encountering persistent errors? Our support team is here to help.