157 lines
4.9 KiB
Markdown
157 lines
4.9 KiB
Markdown
# 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
|
|
|