Mitgliederverwaltung/.plans/open/issue-210-inconsistent-error-response-format.md

Issue #210: Inconsistent Error Response Format

Problem

Different controllers return errors in different formats:

// MemberController
return new JSONResponse(['error' => 'Mitglied nicht gefunden'], Http::STATUS_NOT_FOUND);

// Some controllers might return
return new JSONResponse(['message' => 'Not found'], Http::STATUS_NOT_FOUND);

// Validation errors sometimes include field-level details:
return new JSONResponse(['error' => 'Validation failed', 'fields' => [...]], Http::STATUS_BAD_REQUEST);

This makes frontend error handling difficult.

Impact

• Inconsistent frontend error parsing
• Difficulty implementing global error handling
• Poor developer experience when debugging

Solution

Create a standardized error response format:

class ApiResponse {
    public static function success(mixed $data, int $status = 200): JSONResponse { ... }
    
    public static function error(
        string $message,
        int $status,
        ?array $details = null,
        ?string $errorCode = null
    ): JSONResponse {
        return new JSONResponse([
            'success' => false,
            'error' => [
                'code' => $errorCode ?? self::getDefaultCode($status),
                'message' => $message,
                'details' => $details,
            ]
        ], $status);
    }
}

Standard response format:

{
    "success": true,
    "data": { ... },
    "meta": {
        "total": 42,
        "limit": 20,
        "offset": 0
    }
}

Error response format:

{
    "success": false,
    "error": {
        "code": "MEMBER_NOT_FOUND",
        "message": "Mitglied nicht gefunden",
        "details": { "memberId": 123 }
    }
}

Tasks

• Create ApiResponse utility class
• Define standard error codes (MEMBER_NOT_FOUND, VALIDATION_ERROR, etc.)
• Update all controllers to use ApiResponse::error()
• Update frontend stores to handle new error format
• Document the response format in docs/

Labels

• enhancement
• backend
• frontend
• api
• priority:medium