HTTP Status Codes
The Affelios API uses standard HTTP status codes to indicate the success or failure of requests:2xx Success Codes
2xx Success Codes
200 OK: Request successful, data returned201 Created: Resource successfully created202 Accepted: Request accepted for processing204 No Content: Request successful, no data returned
4xx Client Errors
4xx Client Errors
400 Bad Request: Invalid request data or parameters401 Unauthorized: Authentication required or invalid403 Forbidden: Insufficient permissions for the request404 Not Found: Resource not found409 Conflict: Resource already exists or conflict occurred422 Unprocessable Entity: Valid request but business logic error
5xx Server Errors
5xx Server Errors
500 Internal Server Error: Unexpected server error502 Bad Gateway: Upstream service unavailable503 Service Unavailable: Service temporarily unavailable504 Gateway Timeout: Request timeout
Error Handling Best Practices
Implement Proper Error Handling
Error Handling Strategy
Follow these practices for robust error handling in your applications:
Always Check Status Codes
Always Check Status Codes
HTTP Status Validation:
Implement Retry Logic
Implement Retry Logic
Exponential Backoff:
Log Errors Appropriately
Log Errors Appropriately
Structured Logging:
Handle Different Error Types
Handle Different Error Types
Error Type Handling:
Asynchronous Error Handling
Some operations in the Affelios platform are processed asynchronously, which means they may succeed initially but fail during background processing. This is particularly common with transaction processing.How Asynchronous Processing Works
Queued Operations
Certain operations like transaction creation are queued for background processing to ensure optimal performance and reliability.
- API Request: You submit a transaction via API
- Immediate Response: API returns
201 Created
- Background Processing: Transaction is queued for processing
- Processing: Affelios processes the transaction asynchronously
- Result: Transaction either succeeds or fails during processing
Monitoring Asynchronous Errors
Important: Even though your API request succeeded (returned 2xx status), the actual operation may fail during background processing. These errors are not returned in the API response.
- Navigate to Transactions > Transaction Errors and Failures in the Affelios dashboard
- This section shows all transactions that failed during background processing
- Each error includes details about why the transaction failed
Common Asynchronous Error Scenarios
Common Asynchronous Error Scenarios
Transaction Processing Failures:
- Invalid customer data discovered during processing
- Commission calculation errors
- External system integration failures
- Data validation issues not caught during initial API validation
- Date formatting errors: Unformatted dates that don’t follow ISO 8601 standard
- Initial validation only checks basic data structure
- Complex business logic validation happens during processing
- External dependencies may not be available during API call
- Some validation requires cross-referencing with other data
- Date format validation requires parsing and business logic checks
Monitoring Best Practices
Monitoring Best Practices
Regular Monitoring:
- Check the Transaction Errors dashboard regularly
- Set up alerts for high error rates
- Monitor error patterns to identify systematic issues
- Review error details to understand root causes
- Fix data issues and resubmit failed transactions
- Update integration logic based on error patterns
- Contact support for persistent issues
- Implement better validation before API submission
Monitor and Debug
Debugging Tools
Use these tools and techniques to debug API issues:
Logging Best Practices
Logging Best Practices
Comprehensive Logging:
- Log all API requests and responses
- Log timing information for performance analysis
- Use structured logging for better searchability
Testing with API Tools
Testing with API Tools
Using Postman and Similar Tools:Benefits for Error Debugging:
- Test API requests directly without application code
- Easily modify headers, body, and parameters
- View raw request and response data
- Test different authentication scenarios
- Save and organize API requests for reuse
Quick Start: You can import the Affelios OpenAPI specification directly into Postman. Use the OpenAPI Specification to automatically generate a complete collection with all available endpoints, request examples, and response schemas.
- Isolate issues from application logic
- Test with different data combinations
- Verify authentication and permissions
- Share exact request details with support
- Test error scenarios systematically
Troubleshooting Guide
Common Issues and Solutions
Authentication Issues
Authentication Issues
Problem: Getting 401 Unauthorized errorsSolutions:
- Verify API key is correctly formatted
- Check that key is active and not expired
- Ensure key has required permissions
- Confirm you’re using the correct environment
- Check for typos in the API key
Permission Issues
Permission Issues
Problem: Getting 403 Forbidden errorsSolutions:
- Review API key permissions in dashboard
- Check user role and access level
- Verify resource ownership
- Confirm program access rights
- Request additional permissions if needed
Data Issues
Data Issues
Problem: Getting validation errorsSolutions:
- Review API documentation for field requirements
- Validate data before sending requests
- Check data types and formats
- Ensure required fields are present
- Verify business rule compliance
Asynchronous Processing Issues
Asynchronous Processing Issues
Problem: API requests succeed but operations fail in background processingSolutions:
- Check Transactions > Transaction Errors and Failures in dashboard
- Review error details to understand failure reasons
- Fix data issues and resubmit failed transactions
- Implement better pre-validation before API calls
- Monitor error patterns for systematic issues
- Contact support for persistent processing failures
Date Format Issues
Date Format Issues
Problem: Getting date formatting errors in asynchronous processingCommon Date Format Errors:Examples:
- Using MM/DD/YYYY or DD/MM/YYYY formats
- Missing timezone information
- Using 12-hour format without AM/PM
- Including timezone names instead of offsets
- Using Unix timestamps instead of ISO strings
2024-01-15T10:30:00.000Z
(UTC timezone)2024-01-15T10:30:00.000+00:00
(with timezone offset)2024-01-15
(date only)
- Always use UTC timezone (Z suffix) unless specifically required
- Include milliseconds for precise timestamps
- Validate date formats before sending API requests
- Use your programming language’s ISO 8601 formatting functions
- Check Transactions > Transaction Errors and Failures for date-related failures
Getting Help
Support Resources
If you need additional help with error handling:
- Documentation: Review the API Reference for detailed endpoint information
- Support: Contact support with request IDs for faster resolution
- Community: Join our developer community for tips and best practices
- Status Page: Check our status page for service issues
Next Steps
Now that you understand error handling, you can build more robust integrations with the Affelios API.
- API Testing - Learn about testing your API integrations
- API Authentication - Learn about authentication methods
- API Reference - Explore available endpoints
- Integration Examples - See practical integration examples
- Webhook Setup - Set up real-time notifications