Error Handling and Rate Limiting

When an error occurs, the API returns a standardized error response in the following format:

{
  "_status": "ERR",
  "_error": {
    "code": 422,
    "message": "Validation failed",
    "details": {
      "customer.name": "Name is required",
      "customer.id_number": "Invalid ID number format"
    }
  }
}

Common HTTP Status Codes

• 200 OK: Request successful
• 201 Created: Resource created successfully
• 400 Bad Request: Invalid request data
• 401 Unauthorized: Authentication required or invalid
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource not found
• 422 Unprocessable Entity: Validation errors
• 500 Internal Server Error: Server error

Best Practices for Error Handling

1. Always check the response status

   • Check both HTTP status code and _status field
   • Handle both successful and error responses

2. Implement proper error recovery

   • Retry on temporary failures (e.g., rate limits)
   • Log errors for debugging
   • Provide meaningful error messages to end users

3. Handle specific error codes

   • 401: Re-authenticate and retry
   • 422: Validate input data
   • 429: Implement backoff strategy
   • 5xx: Consider circuit breaker pattern

4. Validation Best Practices

   • Validate data before sending
   • Check required fields
   • Verify data formats
   • Ensure business rule compliance

Rate Limiting

Rate limiting is 3. Handle rate limiting gracefully with exponential backoff

• Standard rate limit: 100 requests per minute per API key
• Burst limit: 10 requests per second
• Rate limit headers are included in responses