Error Handling

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

object

Contains error information

Show Properties

string

Human-readable error description explaining what went wrong

string

Machine-readable error code for programmatic handling

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

authentication_error

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

insufficient_funds

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"
}

invalid_phone_number

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"
}

transfer_not_found

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"
}

kyc_not_verified

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

internal_server_error

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"
}

service_unavailable

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

invalid_request

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"
}

invalid_amount

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;
    }
  }
}

import time
import requests

def make_request_with_retry(url, headers, max_retries=3):
    for i in range(max_retries):
        try:
            response = requests.get(url, headers=headers)
            data = response.json()
            
            if data.get('success') in [True, 'true']:
                return data
            
            # Don't retry for client errors
            if data['error']['code'] in ['authentication_error', 'invalid_request']:
                raise Exception(data['error']['message'])
            
            # Retry for server errors
            if i < max_retries - 1:
                time.sleep(2 ** i)
        except Exception as e:
            if i == max_retries - 1:
                raise e

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 Code	Meaning	Action
200	OK	Check `success` field in response body
400	Bad Request	Fix request parameters
401	Unauthorized	Check API key
404	Not Found	Verify endpoint URL
429	Too Many Requests	Implement rate limiting
500	Internal Server Error	Retry with backoff
503	Service Unavailable	Retry 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.

Getting started

Core Concepts

Error Response Structure

Error Object

Example Error Response

Common Error Codes

Authentication Errors

Transaction Errors

Server Errors

Validation Errors

Error Handling Best Practices

1. Always Check Success Field

2. Implement Retry Logic

3. Use Error Codes for Logic

4. Log Errors for Debugging

5. Provide User-Friendly Messages

HTTP Status Codes

Error Handling Checklist

Need Help?

Contact Support

​Error Response Structure

​Error Object

​Example Error Response

​Common Error Codes

​Authentication Errors

​Transaction Errors

​Server Errors

​Validation Errors

​Error Handling Best Practices

​1. Always Check Success Field

​2. Implement Retry Logic

​3. Use Error Codes for Logic

​4. Log Errors for Debugging

​5. Provide User-Friendly Messages

​HTTP Status Codes

​Error Handling Checklist

​Need Help?

Contact Support

Error Response Structure

Error Object

Example Error Response

Common Error Codes

Authentication Errors

Transaction Errors

Server Errors

Validation Errors

Error Handling Best Practices

1. Always Check Success Field

2. Implement Retry Logic

3. Use Error Codes for Logic

4. Log Errors for Debugging

5. Provide User-Friendly Messages

HTTP Status Codes

Error Handling Checklist

Need Help?