Return insufficient_wallet when Transfer billing fails for zero balance.

Expose a stable error_code on chunked upload finalize so webmail can prompt wallet top-up instead of a generic upload failure.

Co-authored-by: Cursor <cursoragent@cursor.com>

app/Http/Controllers/Api/ChunkedUploadController.php

@@ -6,6 +6,7 @@ use App\Http\Controllers\Controller;
 use App\Services\Identity\MailboxUserResolver;
 use App\Services\Transfer\TransferService;
 use App\Services\Upload\ChunkedUploadService;
+use App\Support\TransferWalletErrors;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Illuminate\Support\Str;
@@ -128,7 +129,12 @@ class ChunkedUploadController extends Controller
                 'retention_days' => $retentionDays,
             ], [$uploadedFile]);
         } catch (RuntimeException $e) {
-            return response()->json(['message' => $e->getMessage()], 422);
+            $payload = ['message' => $e->getMessage()];
+            if (TransferWalletErrors::isInsufficientBalance($e)) {
+                $payload['error_code'] = TransferWalletErrors::CODE_INSUFFICIENT_WALLET;
+            }
+
+            return response()->json($payload, 422);
         } finally {
             $this->uploads->cleanup($validated['upload_id']);
         }

app/Support/TransferWalletErrors.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace App\Support;
+
+use RuntimeException;
+
+class TransferWalletErrors
+{
+    public const CODE_INSUFFICIENT_WALLET = 'insufficient_wallet';
+
+    public static function isInsufficientBalance(RuntimeException $e): bool
+    {
+        $message = strtolower($e->getMessage());
+
+        return str_contains($message, 'insufficient wallet')
+            || str_contains($message, 'top up');
+    }
+}