veza/ERROR_RESPONSE_STANDARD.md

Error Response Format Standardization

INT-006: Standardize error response format

Date: 2025-12-25
Status: Completed

Summary

All error responses in the Veza API now use a consistent, standardized format that matches the APIResponse envelope structure.

Standard Error Response Format

All error responses follow this structure:

{
  "success": false,
  "data": null,
  "error": {
    "code": 1000,
    "message": "Error message",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ],
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2025-12-25T10:30:00Z",
    "context": {
      "user_id": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}

Error Object Fields

• code (number, required): Error code from the error code system (1000-9999)
• message (string, required): Human-readable error message
• details (array, optional): Array of validation error details
  • field (string): Field name that failed validation
  • message (string): Field-specific error message
  • value (string, optional): Invalid value that was provided
• request_id (string, optional): Request ID for tracking and debugging
• timestamp (string, required): ISO 8601 timestamp of when the error occurred
• context (object, optional): Additional context information (user_id, etc.)

Implementation

Backend

All error responses are now standardized through:

1. RespondWithAppError (internal/handlers/error_response.go):

   • Primary function for sending standardized error responses
   • Uses AppError type from internal/errors
   • Automatically includes request_id, timestamp, and context

2. Error Handler Middleware (internal/middleware/error_handler.go):

   • Catches all unhandled errors
   • Converts them to standardized format
   • Uses APIResponse envelope structure

3. Handler Functions:

   • All handlers use RespondWithAppError for errors
   • No direct gin.H{"error": ...} usage
   • Consistent error handling across all endpoints

Frontend

The frontend already handles the standardized format through:

1. parseApiError (apps/web/src/utils/apiErrorHandler.ts):

   • Parses backend error responses
   • Handles multiple response formats (legacy and new)
   • Normalizes to ApiError type

2. ApiError Type (apps/web/src/types/api.ts):

   • Matches backend error structure
   • Includes all standard fields

3. Error Handling:

   • Axios interceptors handle error responses
   • User-friendly error messages displayed
   • Request ID available for debugging

Error Code System

Error codes follow a hierarchical system:

• 1000-1999: Authentication & Authorization errors
• 2000-2999: Validation errors
• 3000-3999: Resource errors (not found, conflict, etc.)
• 4000-4999: Business logic errors
• 5000-5099: Rate limiting errors
• 6000-6999: External service errors
• 9000-9999: Internal server errors

Changes Made

Backend Changes

1. internal/middleware/error_handler.go:

   • Updated to use APIResponse envelope
   • All error responses now include success: false
   • Standardized error object structure
   • Added timestamp to all error responses

2. internal/handlers/webhook_handlers.go:

   • Replaced all gin.H{"error": ...} with RespondWithAppError
   • Consistent error handling across all webhook endpoints
   • Proper error codes and messages

3. Error Response Helpers:

   • RespondWithAppError: Main function for standardized errors
   • RespondWithError: Alternative for simple errors
   • Both use APIResponse envelope

Frontend Compatibility

The frontend already supports the standardized format:

• parseApiError handles {success: false, error: {...}} format
• ApiError type matches backend structure
• Error messages displayed correctly to users

Testing

All error responses should:

1. Use APIResponse envelope with success: false
2. Include all required error fields (code, message, timestamp)
3. Include optional fields when available (request_id, details, context)
4. Use appropriate HTTP status codes
5. Be parseable by frontend parseApiError function

Migration Notes

• Legacy error formats (gin.H{"error": ...}) have been replaced
• All handlers now use RespondWithAppError
• Middleware ensures unhandled errors are standardized
• Frontend handles both old and new formats for backward compatibility

Files Modified

• veza-backend-api/internal/middleware/error_handler.go
• veza-backend-api/internal/handlers/webhook_handlers.go
• Created: ERROR_RESPONSE_STANDARD.md (this document)

Next Steps

1. ✅ Standardize middleware error handler
2. ✅ Update webhook handlers
3. ✅ Verify frontend compatibility
4. ⏳ Audit other handlers for non-standard error responses
5. ⏳ Add integration tests for error format validation