Error Handling Best Practices

Overview

When integrating with CrissCross, it’s important to implement robust error handling to ensure a seamless payment experience. This document outlines best practices for managing errors effectively with the Collect APIs.

Key Error Types

1. Client Errors (4xx):

   • These errors occur due to invalid requests from the merchant (e.g., missing parameters, invalid data).
   • Examples:
     • 400 Bad Request: Incorrect or missing request parameters.
     • 401 Unauthorized: Invalid or missing API key.
     • 404 Not Found: Resource not available (e.g., transaction ID does not exist).

2. Server Errors (5xx):

   • These errors are caused by issues on CrissCross’s side.
   • Examples:
     • 500 Internal Server Error: Temporary system failure.
     • 503 Service Unavailable: CrissCross service is temporarily down or under maintenance.

3. Payment-Specific Errors:

   • These errors occur during payment processing and could result from card issues, insufficient funds, or expired payment methods.

Retry Strategy

Implement retries for idempotent operations and transient failures (for example, timeouts or 5xx errors). Avoid retrying payment creation unless you can guarantee idempotency using your own reference IDs and reconciliation logic.

Example Error Response

Here is an example of a generic error response shape (see the API reference for the exact schema):

1
{
2
  "error": {
3
    "code": "ERROR_CODE",
4
    "message": "Human-readable error message."
5
  }
6
}

Handling Errors in Your Integration

1. Monitor Webhook Notifications:

   • Use webhooks to stay informed about payment statuses and errors. Always implement retry logic for webhook delivery failures on your side.

2. Implement Graceful Error Messages:

   • Display user-friendly error messages when a payment fails. Avoid showing raw error codes to end-users.

3. Log All Errors for Debugging:

   • Log errors with detailed context for troubleshooting. Include request IDs, timestamps, and transaction data.

4. Use Exponential Backoff for Retries:

   • When retrying failed API requests, use exponential backoff to avoid overwhelming the system.

Error Classes and Suggested Actions

Conclusion

Effective error handling is essential for maintaining a smooth payment experience. By leveraging CrissCross’s automatic retries, monitoring webhook notifications, and implementing clear error messages, merchants can minimize disruptions and ensure better customer satisfaction.