Error handling

Common causes:

• Missing or invalid bearer token
• Expired access token
• Incorrect client credentials

Example response:

1
{
2
  "code": "UNAUTHORIZED",
3
  "description": "Missing or invalid bearer token",
4
  "type": "Authentication Error"
5
}

Handling strategy:

• Clear invalid token from storage
• Refresh access token using client credentials flow
• Retry original request with new token

Common causes:

• Missing required fields
• Invalid data formats
• Unsupported values
• Field-specific validation failures

Example response:

1
{
2
  "code": "INVALID_PARAMETER",
3
  "description": "email is required",
4
  "type": "Validation Error",
5
  "field": "email"
6
}

Handling strategy:

• Check if field is present for field-specific errors
• Highlight the problematic field in your UI
• Display user-friendly error message
• Prevent form submission until resolved

Common causes:

• Invalid customer ID
• Non-existent resource references
• Expired or deleted entities

Example response:

1
{
2
  "code": "RESOURCE_NOT_FOUND",
3
  "description": "Customer not found",
4
  "type": "Resource Error"
5
}

Handling strategy:

• Display clear “not found” message to user
• Offer alternative actions (create new resource, search, etc.)
• Log the error for debugging purposes
• Redirect to appropriate fallback page

Common causes:

• Temporary service disruption
• Database connectivity issues
• System overload

Example response:

1
{
2
  "code": "INTERNAL_ERROR",
3
  "description": "Unexpected server-side failure", 
4
  "type": "Server Error"
5
}

Handling strategy:

• Log error details for monitoring and debugging
• Implement exponential backoff for retries
• Limit retry attempts (typically 3-5 attempts)
• Display user-friendly “service unavailable” message
• Provide estimated recovery time if known

Key principles:

• Start with 1-second base delay
• Double delay after each retry (exponential growth)
• Add random jitter to prevent thundering herd
• Cap maximum delay at 30 seconds
• Use for temporary failures only

Implementation steps:

1. Set maximum retry limit (typically 3-5 attempts)
2. Check if error is retryable before attempting
3. Apply exponential backoff between attempts
4. Log each retry attempt for monitoring
5. Fail fast on non-retryable errors

Retryable error conditions:

• Server errors (500+)
• Rate limiting (429)
• Network timeouts
• Connection failures

Scenario: Quote expires before creating payment

1
{
2
  "code": "QUOTE_EXPIRED",
3
  "description": "Quote has expired and can no longer be used",
4
  "type": "Business Error"
5
}

Recovery:

• Generate new quote automatically using original parameters
• Update quote display with new rate and expiry
• Notify user of rate change and request confirmation

Scenario: Customer has insufficient funds for payment

1
{
2
  "code": "INSUFFICIENT_BALANCE",
3
  "description": "Customer balance insufficient for payment amount",
4
  "type": "Business Error"
5
}

Recovery:

• Display funding instructions with required amount
• Show supported funding methods (bank transfer, etc.)
• Provide clear timeline for fund availability
• Offer to pause payment until funds are available

Scenario: Additional KYC verification needed

1
{
2
  "code": "VERIFICATION_REQUIRED", 
3
  "description": "Customer requires additional verification",
4
  "type": "Business Error"
5
}

Recovery:

• Redirect user to KYC verification process
• Explain required documents and timeline
• Save payment progress for completion after verification
• Provide status updates on verification progress

Essential logging elements:

• Error code and type for categorization
• Request context (customer ID, endpoint, request ID)
• User agent and timestamp information
• Stack trace for debugging purposes
• Correlation IDs for request tracing

Logging levels:

• ERROR: All API errors and exceptions
• WARN: Retry attempts and recoverable issues
• INFO: Successful error recoveries
• DEBUG: Detailed troubleshooting information

Message examples by error type:

• INVALID_PARAMETER: “Please check the highlighted field and try again”
• QUOTE_EXPIRED: “Exchange rate expired. We’ve generated a new rate for you”
• INSUFFICIENT_BALANCE: “Please add funds to your account to continue”
• VERIFICATION_REQUIRED: “Additional verification needed to process this payment”

Message guidelines:

• Use simple, non-technical language
• Provide clear next steps
• Include relevant context
• Avoid exposing internal system details

User experience layers:

• Primary: User-friendly message prominently displayed
• Secondary: Recovery actions and next steps
• Tertiary: Technical details (debug mode only)
• Background: Full error logging for troubleshooting

Context-aware help:

• Link to relevant documentation
• Suggest alternative approaches
• Provide contact information for complex issues
• Include estimated resolution times

Critical test scenarios:

• Validation errors with missing required fields
• Authentication failures with invalid tokens
• Server errors with proper retry logic
• Business logic errors with appropriate recovery
• Network timeouts and connection failures
• Rate limiting and backoff behavior

Testing strategies:

• Mock API responses for different error codes
• Simulate network failures and timeouts
• Test retry logic with controlled delays
• Validate user experience during errors
• Monitor error logging and metrics