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:

```json
{
  "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