feat: enhance API error handling and response structure; introduce ApiException for V2 error codes

apps/mobile/packages/domain/lib/src/exceptions/app_exception.dart

@@ -286,6 +286,54 @@ class NoActiveShiftException extends ShiftException {
 // NETWORK/GENERIC EXCEPTIONS
 // ============================================================
 
+// ============================================================
+// API EXCEPTIONS (mapped from V2 error envelope codes)
+// ============================================================
+
+/// Thrown when the V2 API returns a non-success response.
+///
+/// Carries the full error envelope so callers can inspect details.
+class ApiException extends AppException {
+  /// Creates an [ApiException].
+  const ApiException({
+    required String apiCode,
+    required String apiMessage,
+    this.statusCode,
+    this.details,
+    super.technicalMessage,
+  }) : super(code: apiCode);
+
+  /// The HTTP status code (e.g. 400, 404, 500).
+  final int? statusCode;
+
+  /// The V2 API error code string (e.g. 'VALIDATION_ERROR').
+  String get apiCode => code;
+
+  /// Optional details from the error envelope.
+  final dynamic details;
+
+  @override
+  String get messageKey {
+    switch (code) {
+      case 'VALIDATION_ERROR':
+        return 'errors.generic.validation_error';
+      case 'NOT_FOUND':
+        return 'errors.generic.not_found';
+      case 'FORBIDDEN':
+        return 'errors.generic.forbidden';
+      case 'UNAUTHENTICATED':
+        return 'errors.auth.not_authenticated';
+      case 'CONFLICT':
+        return 'errors.generic.conflict';
+      default:
+        if (statusCode != null && statusCode! >= 500) {
+          return 'errors.generic.server_error';
+        }
+        return 'errors.generic.unknown';
+    }
+  }
+}
+
 /// Thrown when there is no network connection.
 class NetworkException extends AppException {
   const NetworkException({super.technicalMessage})