fix(files): classify upload failures instead of matching their wording

Bugbot round 2. uploadWorkspaceFile had the same outer-catch rewrap that
updateWorkspaceFileContent did, so a blown storage quota reached the route as a
bare Error and the v2 handler recovered the status by substring-matching the
message. Any rewording silently demoted a 413 to a 500.

- uploadWorkspaceFile rethrows a classified failure untouched and attaches cause
  to the generic wrap.
- FileConflictError is now an OrchestrationError('conflict'), so a duplicate name
  classifies like every other conflict. Its 'FILE_EXISTS' discriminator had no
  readers and is gone; the instanceof checks elsewhere still hold.
- The v2 upload handler uses v2CaughtOrchestrationError, dropping all three
  string matches.

Also documents that bulk-archive is best-effort: unknown or already-archived ids
are skipped rather than failing the call, and deletedItems is what actually
happened. That asymmetry with the single-id DELETE was undocumented.

Author: TheodoreSpeaks

apps/docs/openapi-v2-files-audit.json

@@ -1051,7 +1051,7 @@
       "post": {
         "operationId": "bulkArchiveFileItems",
         "summary": "Archive Files and Folders",
-        "description": "Archive (soft delete) files and/or folders in one call. Archiving a folder cascades to everything under it, so `deletedItems` reports totals larger than the selection. Archived items remain listable via `scope=archived` and can be restored.",
+        "description": "Archive (soft delete) files and/or folders in one call. Archiving a folder cascades to everything under it, so `deletedItems` reports totals larger than the selection. Archived items remain listable via `scope=archived` and can be restored.\n\n**This endpoint is best-effort and idempotent.** Ids that do not exist, belong to another workspace, or are already archived are skipped rather than failing the request — the call still returns `200`. `deletedItems` is what was actually archived, so compare it against your selection if you need to detect that something was skipped. The single-item `DELETE /api/v2/files/{fileId}` does return `404` for a missing id.",
         "tags": ["Files"],
         "x-codeSamples": [
           {

apps/sim/app/api/v2/files/route.test.ts

@@ -53,6 +53,7 @@ vi.mock('@sim/audit', () => ({
   AuditResourceType: { FILE: 'file' },
 }))
 
+import { OrchestrationError } from '@/lib/core/orchestration/types'
 import { GET, POST } from '@/app/api/v2/files/route'
 
 const WS = 'workspace-1'
@@ -287,11 +288,35 @@ describe('POST /api/v2/files', () => {
   })
 
   it('404s when the target folder does not exist', async () => {
-    mockUploadWorkspaceFile.mockRejectedValue(new Error('Target folder not found'))
+    mockUploadWorkspaceFile.mockRejectedValue(
+      new OrchestrationError('not_found', 'Target folder not found')
+    )
 
     const res = await callUpload(`workspaceId=${WS}&folderId=missing`)
 
     expect(res.status).toBe(404)
     expect((await res.json()).error.code).toBe('NOT_FOUND')
   })
+
+  it('413s on a blown storage quota by class, not by message wording', async () => {
+    mockUploadWorkspaceFile.mockRejectedValue(
+      new OrchestrationError('payload_too_large', 'Quota exceeded for this workspace')
+    )
+
+    const res = await callUpload(`workspaceId=${WS}`)
+
+    expect(res.status).toBe(413)
+    expect((await res.json()).error.code).toBe('PAYLOAD_TOO_LARGE')
+  })
+
+  it('409s on a duplicate-name conflict by class', async () => {
+    mockUploadWorkspaceFile.mockRejectedValue(
+      new OrchestrationError('conflict', 'A file named "data.csv" already exists in this workspace')
+    )
+
+    const res = await callUpload(`workspaceId=${WS}`)
+
+    expect(res.status).toBe(409)
+    expect((await res.json()).error.code).toBe('CONFLICT')
+  })
 })

apps/sim/app/api/v2/files/route.ts

@@ -15,7 +15,6 @@ import {
 } from '@/lib/core/utils/stream-limits'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import {
-  FileConflictError,
   getWorkspaceFile,
   listWorkspaceFiles,
   uploadWorkspaceFile,
@@ -26,6 +25,7 @@ import { v2ApiGateError } from '@/app/api/v2/lib/gate'
 import {
   decodeCursor,
   encodeCursor,
+  v2CaughtOrchestrationError,
   v2CursorList,
   v2Data,
   v2Error,
@@ -226,17 +226,12 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       return v2Error('PAYLOAD_TOO_LARGE', error.message)
     }
 
-    const message = getErrorMessage(error, 'Failed to upload file')
-    if (error instanceof FileConflictError || message.includes('already exists')) {
-      return v2Error('CONFLICT', message)
-    }
-    if (message === 'Target folder not found') {
-      return v2Error('NOT_FOUND', message)
-    }
-    if (message.includes('Storage limit') || message.includes('storage limit')) {
-      return v2Error('PAYLOAD_TOO_LARGE', 'Storage limit exceeded')
-    }
+    // Conflicts, a missing target folder, and a blown storage quota all arrive classified
+    // now, so the status comes off the error's code rather than its wording.
+    const classified = v2CaughtOrchestrationError(error)
+    if (classified) return classified
 
+    const message = getErrorMessage(error, 'Failed to upload file')
     logger.error('Error uploading file', { error: message })
     return v2Error('INTERNAL_ERROR', 'Internal server error')
   }

apps/sim/lib/uploads/contexts/workspace/workspace-file-manager.ts

@@ -52,10 +52,15 @@ const logger = createLogger('WorkspaceFileStorage')
 
 export type WorkspaceFileScope = 'active' | 'archived' | 'all'
 
-export class FileConflictError extends Error {
-  readonly code = 'FILE_EXISTS' as const
+/**
+ * An {@link OrchestrationError} so every surface reaches 409 by class rather than by
+ * searching the message for "already exists". Carries the inherited `code: 'conflict'`;
+ * the old `'FILE_EXISTS'` discriminator had no readers.
+ */
+export class FileConflictError extends OrchestrationError {
   constructor(name: string) {
-    super(`A file named "${name}" already exists in this workspace`)
+    super('conflict', `A file named "${name}" already exists in this workspace`)
+    this.name = 'FileConflictError'
   }
 }
 
@@ -424,8 +429,15 @@ export async function uploadWorkspaceFile(
         )
         continue
       }
+      // A classified failure (a blown storage quota, a missing target folder) keeps its class:
+      // re-wrapping it in a bare Error is what forced every caller to substring-match the
+      // message to recover the status.
+      const classified = asOrchestrationError(error)
+      if (classified) throw classified
       logger.error(`Failed to upload workspace file ${fileName}:`, error)
-      throw new Error(`Failed to upload file: ${getErrorMessage(error, 'Unknown error')}`)
+      throw new Error(`Failed to upload file: ${getErrorMessage(error, 'Unknown error')}`, {
+        cause: error,
+      })
     }
   }