Error Handling

Comprehensive error handling is essential for building robust integrations with the Tonder API. This guide covers error response formats, common error scenarios, and HTTP status codes.

Error Response Format

All errors follow a consistent format:

{
  "error": {
    "code": "validation_error",
    "message": "Amount must be greater than 0",
    "type": "request_error",
    "details": {
      "field": "amount",
      "received_value": -10.00
    }
  },
  "request_id": "req_abc123"
}

Where:

Field	Type	Description
`error.code`	string	Specific error code
`error.message`	string	Human-readable error message
`error.type`	string	Error category
`error.details`	object	Additional error context
`request_id`	string	Unique request identifier for support

HTTP Status Codes

Here are the HTTP status codes that you may receive in the response:

Success Codes

Code	Category	Description	Action
200	Success	Request successful	Continue
201	Success	Transaction created	Continue
202	Success	Transaction accepted (async processing)	Monitor status

Client Error Codes

Code	Category	Description	Action
400	Client Error	Invalid request format	Fix request
401	Client Error	Authentication failed	Check credentials
402	Client Error	Payment required/declined	Try different method
404	Client Error	Resource not found	Check ID
422	Client Error	Validation failed	Fix data
429	Client Error	Rate limit exceeded	Retry with backoff

Server Error Codes

Code	Category	Description	Action
500	Server Error	Internal server error	Retry request
502	Server Error	Bad gateway	Retry request
503	Server Error	Service unavailable	Retry later

Common Error Categories

Errors can belong to the following categories:

Authentication Errors

Code	Description	Solution
`invalid_api_key`	API key not found	Check API key
`invalid_authentication`	HMAC signature invalid or authentication failed	Verify signature calculation and field mappings
`authentication_required`	Missing authentication headers	Include required authentication headers

Validation Errors

Code	Description	Solution
`missing_field`	Required field missing	Include required field
`invalid_amount`	Amount out of range	Use valid amount (0.01 - 15,000,000)
`invalid_currency`	Currency not supported	Use supported currency
`invalid_email`	Email format invalid	Use valid email format

Payment Errors

Code	Description	Solution
`card_declined`	Card declined by issuer	Try different card
`insufficient_funds`	Not enough funds	Try different payment method
`expired_card`	Card has expired	Use valid card
`invalid_card`	Card number invalid	Check card details
`processing_error`	Temporary processing error	Retry request

Withdrawal Errors

Code	Description	Solution
`invalid_clabe`	CLABE number invalid	Verify CLABE format
`institution_not_found`	Bank code not found	Use valid institution code
`insufficient_balance`	Not enough balance	Check account balance
`beneficiary_blocked`	Beneficiary account blocked	Contact bank

Basic Error Handling

Here are some examples of how to handle errors in different programming languages:

Error Handling Examples

public class TonderApiException extends Exception {
    private final String errorCode;
    private final String errorType;
    private final int statusCode;
    
    // Constructor and getters...
}

public static PaymentResponse processPaymentWithErrorHandling(PaymentRequest request) {
    try {
        return processPayment(request);
        
    } catch (TonderApiException e) {
        switch (e.getErrorCode()) {
            case "card_declined":
                // Try alternative payment method
                return tryAlternativePayment(request);
                
            case "processing_error":
                // Retry with exponential backoff
                return retryPayment(request);
                
            case "invalid_authentication":
                // Check HMAC signature calculation and business configuration
                return fixAuthenticationAndRetry(request);
                
            case "invalid_amount":
                // Fix amount and retry
                request.setAmount(request.getAmount().max(BigDecimal.ONE));
                return processPayment(request);
                
            default:
                throw e; // Re-throw unhandled errors
        }
    }
}

Common Troubleshooting

Here are some common troubleshooting checks for different error scenarios:

Authentication Issues

Payment Failures

Validation Errors

Next Steps

Review Webhooks for real-time error notifications
Check Status Checking for transaction monitoring
Learn about Payment Methods for method-specific error handling
Explore Mexican Banking Reference for regional validation

Getting Started

API Reference

Payment Processing

Integration

Regional Reference

Resources

Error Handling

Error Response Format

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Common Error Categories

Authentication Errors

Validation Errors

Payment Errors

Withdrawal Errors

Basic Error Handling

Common Troubleshooting

Next Steps

Getting Started

API Reference

Payment Processing

Integration

Regional Reference

Resources

​Error Response Format

​HTTP Status Codes

​Success Codes

​Client Error Codes

​Server Error Codes

​Common Error Categories

​Authentication Errors

​Validation Errors

​Payment Errors

​Withdrawal Errors

​Basic Error Handling

​Common Troubleshooting

​Next Steps

Error Response Format

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Common Error Categories

Authentication Errors

Validation Errors

Payment Errors

Withdrawal Errors

Basic Error Handling

Common Troubleshooting

Next Steps