Error Handling

Error Handling

The API uses conventional HTTP response codes and returns detailed error messages in JSON format.

HTTP Status Codes

Error Response Format

All error responses follow this structure:

{
  "error": "error_code",
  "message": "Human-readable error message",
  "details": {
    "field": "email",
    "issue": "Email address is already registered"
  }
}

Common Error Codes

• invalid_request - Malformed request body or parameters
• authentication_failed - Invalid credentials
• token_expired - Access token has expired
• insufficient_permissions - User lacks required permissions
• resource_not_found - Requested resource doesn't exist
• validation_error - Input validation failed
• rate_limit_exceeded - Too many requests

Error Handling Best Practices

• Always check HTTP status codes
• Parse and display error messages to users
• Implement retry logic with exponential backoff
• Log errors for debugging
• Handle token expiration gracefully with refresh logic