Error Handling

Error Handling

All Cashela API endpoints return errors in a consistent, machine-readable JSON format. This guide explains the error structure, common error codes, and best practices for handling failures in your integration.

---

Error Response Structure

All error responses follow this consistent format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {},
    "doc_url": "https://docs.cashela.com/errors#error-code"
  },
  "request_id": "req_01HJ3KBCD8E9F0G1H2I3J4K5L6"
}

Fields

Field	Type	Description
success	boolean	Always false for error responses
error.code	string	Machine-readable error code for programmatic handling
error.message	string	Human-readable description, safe to display to users for certain error types
error.details	object	Additional context, field-specific validation errors, or parameters related to the error
error.doc_url	string	Link to documentation explaining this error type
request_id	string	Unique identifier for this request. Include when contacting support

---

HTTP Status Codes

Cashela uses conventional HTTP status codes to indicate success or failure:

Success Codes (2xx)

Code	Status	Meaning
200	OK	Request succeeded. Response body contains the requested data
201	Created	Resource successfully created (e.g., transaction, quotation)
202	Accepted	Request accepted for processing but not yet completed
204	No Content	Request succeeded with no response body to return

Client Error Codes (4xx)

Code	Status	Meaning	Action
400	Bad Request	Malformed request syntax or invalid JSON	Fix request format
401	Unauthorized	Invalid or missing authentication credentials	Verify API credentials
403	Forbidden	Valid credentials but insufficient permissions	Check IP allowlist or account permissions
404	Not Found	Requested resource doesn’t exist	Verify endpoint URL and resource ID
405	Method Not Allowed	HTTP method not supported for this endpoint	Use correct HTTP method (GET, POST, etc.)
409	Conflict	Request conflicts with current state (e.g., duplicate idempotency key)	Review conflict details and adjust request
422	Unprocessable Entity	Request syntax valid but business logic validation failed	Fix validation errors in request data
429	Too Many Requests	Rate limit exceeded	Implement exponential backoff and retry

Server Error Codes (5xx)

Code	Status	Meaning	Action
500	Internal Server Error	Unexpected server error	Retry with exponential backoff
502	Bad Gateway	Upstream service unavailable	Retry after brief delay
503	Service Unavailable	Temporary service interruption	Check status page, retry with backoff
504	Gateway Timeout	Request timeout	Retry with same idempotency key

Important: 5xx errors are rare and typically transient. Always implement retry logic with exponential backoff for these errors.

---

Error Types

Cashela categorizes errors into distinct types for easier handling:

Authentication Errors

Error Code	Description	Resolution
UNAUTHORIZED	Missing or invalid API credentials	Verify your Business Key and Secret are correct
INVALID_API_KEY	API key format is invalid	Check for typos or encoding issues
EXPIRED_CREDENTIALS	API credentials have been revoked	Generate new credentials in your dashboard
IP_NOT_ALLOWED	Request from non-allowlisted IP	Add your server IP to the allowlist

Validation Errors

Error Code	Description	Resolution
INVALID_INPUT	Malformed request body or invalid JSON	Check JSON syntax and encoding
MISSING_REQUIRED_FIELD	Required parameter not provided	Include all required fields
INVALID_FIELD_FORMAT	Field value doesn’t match expected format	Check field type and format requirements
INVALID_DOCUMENT	Document number failed validation	Verify document matches country requirements
INVALID_EMAIL	Email format is invalid	Provide valid email address
INVALID_PHONE	Phone number format is invalid	Use E.164 format (e.g., +1234567890)
AMOUNT_TOO_LOW	Amount below minimum threshold	Check minimum amount for payment method
AMOUNT_TOO_HIGH	Amount exceeds maximum limit	Split into multiple transactions or contact support

Transaction Errors

Error Code	Description	Resolution
TRANSACTION_NOT_FOUND	Transaction ID doesn’t exist	Verify transaction ID is correct
TRANSACTION_EXPIRED	Transaction or quotation has expired	Create new transaction
TRANSACTION_CANCELLED	Transaction was cancelled	Create new transaction if needed
DUPLICATE_TRANSACTION	Transaction with same external_identifier exists	Use unique identifier per transaction
INSUFFICIENT_FUNDS	Account balance too low	Add funds to your business wallet

Idempotency Errors

Error Code	Description	Resolution
IDEMPOTENCY_CONFLICT	Same key used with different request body	Use new idempotency key or send identical request
IDEMPOTENCY_KEY_REQUIRED	POST request missing Idempotency-Key header	Include UUID v4 in header
INVALID_IDEMPOTENCY_KEY	Key format is invalid	Use valid UUID v4 format

Payment Method Errors

Error Code	Description	Resolution
PAYMENT_METHOD_NOT_FOUND	Invalid payment method code	Use valid code from Get Payment Methods
PAYMENT_METHOD_UNAVAILABLE	Method temporarily unavailable	Try alternative method or retry later
UNSUPPORTED_COUNTRY	Country not supported for method	Choose different country or method
UNSUPPORTED_CURRENCY	Currency not supported	Check supported currencies

Rate Limiting Errors

Error Code	Description	Resolution
RATE_LIMITED	Too many requests in time window	Wait and retry with exponential backoff
QUOTA_EXCEEDED	Monthly transaction quota reached	Contact support to increase limits

---

Validation Error Details

When a validation error occurs, the details object contains field-specific error messages:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "email": "Invalid email format. Expected: user@domain.com",
      "amount": "Amount must be between 10.00 and 50000.00 MXN",
      "document_number": "Invalid format for IFE. Expected pattern: XXXX000000XXXXXX00",
      "phone": "Phone number must be in E.164 format: +521234567890"
    }
  },
  "request_id": "req_01HJ3KBCD8E9F0G1H2I3J4K5L6"
}

Processing validation errors:

function handleValidationErrors(errorResponse) {
  const { details } = errorResponse.error;

  // Map API field names to form field names
  const fieldMapping = {
    'email': 'customerEmail',
    'document_number': 'documentId',
    'amount': 'paymentAmount'
  };

  // Display errors to user
  Object.entries(details).forEach(([field, message]) => {
    const formField = fieldMapping[field] || field;
    displayFieldError(formField, message);
  });
}

---

Error Handling Best Practices

1. Always Check the Success Field

async function makeApiRequest(endpoint, data) {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: getAuthHeaders(),
    body: JSON.stringify(data)
  });

  const result = await response.json();

  // Always check success field, not just HTTP status
  if (!result.success) {
    throw new CashelaApiError(result.error, result.request_id);
  }

  return result.data;
}

2. Handle Errors by Code, Not Message

Messages may change; codes are stable:

function handleApiError(error) {
  switch (error.code) {
    case 'UNAUTHORIZED':
    case 'INVALID_API_KEY':
      // Credential issues - alert operations team
      notifyOperations('API credentials invalid');
      break;

    case 'VALIDATION_ERROR':
      // User input issue - show errors to user
      displayValidationErrors(error.details);
      break;

    case 'RATE_LIMITED':
      // Temporary - retry with backoff
      return scheduleRetry(error);

    case 'INSUFFICIENT_FUNDS':
      // Balance issue - alert finance team
      notifyFinance('Low balance alert');
      break;

    default:
      // Unknown error - log and alert
      logError(error);
      showGenericError();
  }
}

3. Implement Exponential Backoff for Retries

import time
import random

def retry_with_backoff(func, max_retries=5, base_delay=1):
    """Retry function with exponential backoff and jitter."""
    for attempt in range(max_retries):
        try:
            return func()
        except RetryableError as e:
            if attempt == max_retries - 1:
                raise

            # Calculate delay with exponential backoff + jitter
            delay = base_delay * (2 ** attempt)
            jitter = random.uniform(0, delay * 0.1)
            total_delay = delay + jitter

            print(f"Attempt {attempt + 1} failed. Retrying in {total_delay:.2f}s...")
            time.sleep(total_delay)

    raise MaxRetriesExceeded()

# Usage
def create_transaction():
    response = api.create_deposit(transaction_data)
    if response.error and response.error.code in ['RATE_LIMITED', 'INTERNAL_ERROR', 'SERVICE_UNAVAILABLE']:
        raise RetryableError(response.error)
    return response

result = retry_with_backoff(create_transaction)

4. Log Request IDs for Support

class CashelaApiError extends Error {
  constructor(error, requestId) {
    super(error.message);
    this.code = error.code;
    this.details = error.details;
    this.requestId = requestId;

    // Log for debugging and support
    console.error(`Cashela API Error [${requestId}]: ${error.code} - ${error.message}`);
  }
}

// When contacting support, include the request_id
function reportErrorToSupport(error) {
  return {
    message: `API error occurred`,
    requestId: error.requestId,  // Always include this
    errorCode: error.code,
    timestamp: new Date().toISOString()
  };
}

5. Display User-Friendly Messages

const USER_MESSAGES = {
  'VALIDATION_ERROR': 'Please check your information and try again.',
  'PAYMENT_METHOD_UNAVAILABLE': 'This payment method is temporarily unavailable. Please try another option.',
  'INSUFFICIENT_FUNDS': 'We are unable to process this transaction at the moment. Please try again later.',
  'RATE_LIMITED': 'Too many attempts. Please wait a moment and try again.',
  'INTERNAL_ERROR': 'Something went wrong on our end. Please try again in a few minutes.'
};

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

---

Retryable vs Non-Retryable Errors

Retryable Errors (Safe to Retry)

These errors are transient and may succeed on retry:

Error Code	Retry Strategy
RATE_LIMITED	Wait for Retry-After header or use exponential backoff
INTERNAL_ERROR	Retry up to 3 times with exponential backoff
SERVICE_UNAVAILABLE	Check status page, retry with backoff
BAD_GATEWAY	Retry after 5-10 seconds
GATEWAY_TIMEOUT	Retry immediately with same idempotency key

Non-Retryable Errors (Do Not Retry)

These errors require fixing the request or account:

Error Code	Action Required
UNAUTHORIZED	Fix credentials
VALIDATION_ERROR	Fix request data
INSUFFICIENT_FUNDS	Add funds to account
PAYMENT_METHOD_NOT_FOUND	Use valid payment method
IDEMPOTENCY_CONFLICT	Use new idempotency key

---

Related Documentation

• Idempotency – Safe retry implementation
• Rate Limits – Rate limit details
• Webhook Errors – Handling webhook delivery failures
• Field Validation – Input validation rules