refactor(tables): classify failures by type instead of by message text

The table module decided HTTP statuses by searching error messages for
phrases. `VALIDATION_MESSAGE_FRAGMENTS` and `ROW_WRITE_ERROR_PATTERNS` held 32
substrings between them, and fifteen more lists were inlined in routes — 83
matchers over 17 files, each its own copy of the guesswork and already drifted
apart. It made message wording load-bearing: `TableRowLimitError`'s own doc
comment noted that its text had to contain "row limit" for a route to answer
400, and adding "already exists" to a rename message silently demoted a 409 to
a 400 (the bug fixed one commit ago, by adding another special case).

Services now throw `OrchestrationError`, which carries the transport-neutral
`OrchestrationErrorCode` the layers above already speak. Classification is one
`instanceof` in `orchestrationErrorResponse` (UI + v1) and
`v2CaughtOrchestrationError` (v2). Every pattern list is gone. Wording is free
to change; an unclassified error still becomes a generic 500, which is what an
unexpected fault should be.

`asOrchestrationError` walks the `cause` chain rather than testing the caught
value directly: drizzle wraps a throw raised inside a transaction callback in a
`DrizzleQueryError` whose own message is the failed SQL, so a bare `instanceof`
would drop every failure raised inside `withLockedTable`. That is the same
reason `rootErrorMessage` had to dig for a root cause before.

Three throws stay bare `Error` deliberately — `Table ID mismatch`, `Workspace
ID mismatch`, and `Failed to build upsert conflict predicate` are internal
invariants no consumer classified, and they keep falling through to a 500.
`Insufficient capacity` was in the pattern list with no producer anywhere in
the codebase.

Status changes, all deliberate:

- `'forbidden'` joins the code union so the table-row-limit ceiling keeps its
  403; without it this refactor would have flattened it to 400.
- import-async's table-limit rejection: 400 -> 403, matching the two other
  create routes it had drifted from.
- Renaming a table to an invalid name: 500 -> 400. `validateTableName`
  messages don't contain "Invalid", so no matcher ever caught them.
- Restoring a table that isn't archived, or into an archived workspace:
  500 -> 400.
- A duplicate *column* name stays `validation`/400 rather than becoming a 409
  like a duplicate table name. Both v1 and the orchestration have always
  answered 400 for it; changing a published status is not this refactor's job.

The twelve tests that changed were asserting the substring mechanism itself,
constructing plain `Error`s with magic strings. They now assert the real
contract, plus new cases pinning that identical wording carrying no
classification stays internal and keeps its message off the wire.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YGzbVDZpe2dEALbu2BUU8a

Author: TheodoreSpeaks

apps/sim/app/api/table/[tableId]/columns/route.test.ts

@@ -57,6 +57,7 @@ vi.mock('@/app/api/table/utils', () => ({
   tableLockErrorResponse: () => null,
 }))
 
+import { OrchestrationError } from '@/lib/core/orchestration/types'
 import { PATCH } from '@/app/api/table/[tableId]/columns/route'
 
 const WORKSPACE_ID = '11111111-1111-4111-8111-111111111111'
@@ -166,7 +167,10 @@ describe('PATCH /api/table/[tableId]/columns — pre-flight guards', () => {
     // Stands in for the race the guards cannot close: the column stopped being
     // a currency between the snapshot the guards read and this write.
     mockUpdateColumnCurrency.mockRejectedValue(
-      new Error('Cannot set currency on column "amount" of type "string"')
+      new OrchestrationError(
+        'validation',
+        'Cannot set currency on column "amount" of type "string"'
+      )
     )
 
     const response = await patch({ name: 'renamed', currencyCode: 'USD' })

apps/sim/app/api/table/[tableId]/columns/run/route.ts

@@ -8,7 +8,12 @@ import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { TableQueryValidationError } from '@/lib/table/errors'
 import { toLegacyFilter } from '@/lib/table/query-builder/converters'
 import { runWorkflowColumn } from '@/lib/table/workflow-columns'
-import { accessError, checkAccess, tableFilterError } from '@/app/api/table/utils'
+import {
+  accessError,
+  checkAccess,
+  orchestrationErrorResponse,
+  tableFilterError,
+} from '@/app/api/table/utils'
 
 const logger = createLogger('TableRunColumnAPI')
 
@@ -66,9 +71,8 @@ export const POST = withRouteHandler(async (request: NextRequest, { params }: Ro
     if (error instanceof TableQueryValidationError) {
       return NextResponse.json({ error: error.message }, { status: 400 })
     }
-    if (error instanceof Error && error.message === 'Invalid workspace ID') {
-      return NextResponse.json({ error: 'Invalid workspace ID' }, { status: 400 })
-    }
+    const classified = orchestrationErrorResponse(error)
+    if (classified) return classified
     logger.error(`run-column failed:`, error)
     return NextResponse.json({ error: 'Failed to run columns' }, { status: 500 })
   }

apps/sim/app/api/table/[tableId]/import/route.test.ts

@@ -79,6 +79,7 @@ vi.mock('@/lib/table/billing', () => ({
     limit >= 0 && current + added > limit,
 }))
 
+import { OrchestrationError } from '@/lib/core/orchestration/types'
 import { TableLockedError } from '@/lib/table/mutation-locks'
 import { POST } from '@/app/api/table/[tableId]/import/route'
 
@@ -372,7 +373,10 @@ describe('POST /api/table/[tableId]/import', () => {
 
   it('surfaces unique violations from importAppendRows as 400', async () => {
     mockImportAppendRows.mockRejectedValueOnce(
-      new Error('Row 1: Column "name" must be unique. Value "Alice" already exists in row row_xxx')
+      new OrchestrationError(
+        'validation',
+        'Row 1: Column "name" must be unique. Value "Alice" already exists in row row_xxx'
+      )
     )
     const response = await callPost(
       createFormData(createCsvFile('name,age\nAlice,30'), { mode: 'append' })
@@ -516,7 +520,9 @@ describe('POST /api/table/[tableId]/import', () => {
     })
 
     it('surfaces column-creation failures from importAppendRows as 400', async () => {
-      mockImportAppendRows.mockRejectedValueOnce(new Error('Column "email" already exists'))
+      mockImportAppendRows.mockRejectedValueOnce(
+        new OrchestrationError('validation', 'Column "email" already exists')
+      )
       const response = await callPost(
         createFormData(createCsvFile('name,age,email\nAlice,30,a@x.io'), {
           mode: 'append',
@@ -529,7 +535,9 @@ describe('POST /api/table/[tableId]/import', () => {
     })
 
     it('surfaces row insert failures without success when schema was mutated', async () => {
-      mockImportAppendRows.mockRejectedValueOnce(new Error('must be unique'))
+      mockImportAppendRows.mockRejectedValueOnce(
+        new OrchestrationError('validation', 'must be unique')
+      )
       const response = await callPost(
         createFormData(createCsvFile('name,age,email\nAlice,30,a@x.io'), {
           mode: 'append',

apps/sim/app/api/table/[tableId]/import/route.ts

@@ -14,6 +14,7 @@ import {
 import { ianaTimezoneSchema } from '@/lib/api/contracts/user'
 import { getValidationErrorMessage } from '@/lib/api/server'
 import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { asOrchestrationError, statusForOrchestrationError } from '@/lib/core/orchestration/types'
 import { isMultipartError, readMultipart } from '@/lib/core/utils/multipart'
 import { generateRequestId } from '@/lib/core/utils/request'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
@@ -349,21 +350,13 @@ export const POST = withRouteHandler(async (request: NextRequest, { params }: Ro
           createdColumns: additions.length,
           error: message,
         })
-        const isClientError =
-          message.includes('row limit') ||
-          message.includes('Insufficient capacity') ||
-          message.includes('Schema validation') ||
-          message.includes('must be unique') ||
-          message.includes('Row size exceeds') ||
-          message.includes('already exists') ||
-          message.includes('Invalid column name') ||
-          /^Row \d+:/.test(message)
+        const classified = asOrchestrationError(err)
         return NextResponse.json(
           {
-            error: isClientError ? message : 'Failed to import CSV',
+            error: classified ? classified.message : 'Failed to import CSV',
             data: { insertedCount: 0 },
           },
-          { status: isClientError ? 400 : 500 }
+          { status: classified ? statusForOrchestrationError(classified.code) : 500 }
         )
       }
     }
@@ -400,17 +393,12 @@ export const POST = withRouteHandler(async (request: NextRequest, { params }: Ro
         },
       })
     } catch (err) {
-      const message = toError(err).message
-      const isClientError =
-        message.includes('row limit') ||
-        message.includes('Schema validation') ||
-        message.includes('must be unique') ||
-        message.includes('Row size exceeds') ||
-        message.includes('already exists') ||
-        message.includes('Invalid column name') ||
-        /^Row \d+:/.test(message)
-      if (isClientError) {
-        return NextResponse.json({ error: message }, { status: 400 })
+      const classified = asOrchestrationError(err)
+      if (classified) {
+        return NextResponse.json(
+          { error: classified.message },
+          { status: statusForOrchestrationError(classified.code) }
+        )
       }
       throw err
     }
@@ -419,17 +407,12 @@ export const POST = withRouteHandler(async (request: NextRequest, { params }: Ro
     if (lockError) return lockError
     if (isMultipartError(error)) return multipartErrorResponse(error)
 
-    const message = toError(error).message
     logger.error(`[${requestId}] CSV import into existing table failed:`, error)
 
-    const isClientError =
-      message.includes('CSV file has no') ||
-      message.includes('already exists') ||
-      message.includes('Invalid column name')
-
+    const classified = asOrchestrationError(error)
     return NextResponse.json(
-      { error: isClientError ? message : 'Failed to import CSV' },
-      { status: isClientError ? 400 : 500 }
+      { error: classified ? classified.message : 'Failed to import CSV' },
+      { status: classified ? statusForOrchestrationError(classified.code) : 500 }
     )
   } finally {
     fileStream?.destroy()

apps/sim/app/api/table/[tableId]/rows/[rowId]/route.ts

@@ -1,7 +1,6 @@
 import { db } from '@sim/db'
 import { userTableRows } from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
-import { toError } from '@sim/utils/errors'
 import { and, eq } from 'drizzle-orm'
 import { type NextRequest, NextResponse } from 'next/server'
 import {
@@ -21,7 +20,7 @@ import { rowWireTranslators } from '@/app/api/table/row-wire'
 import {
   accessError,
   checkAccess,
-  rootErrorMessage,
+  orchestrationErrorResponse,
   rowWriteErrorResponse,
   tableLockErrorResponse,
 } from '@/app/api/table/utils'
@@ -175,10 +174,6 @@ export const PATCH = withRouteHandler(async (request: NextRequest, context: RowR
       },
     })
   } catch (error) {
-    if (rootErrorMessage(error) === 'Row not found') {
-      return NextResponse.json({ error: 'Row not found' }, { status: 404 })
-    }
-
     const response = rowWriteErrorResponse(error)
     if (response) return response
 
@@ -233,11 +228,8 @@ export const DELETE = withRouteHandler(async (request: NextRequest, context: Row
     const lockError = tableLockErrorResponse(error)
     if (lockError) return lockError
 
-    const errorMessage = toError(error).message
-
-    if (errorMessage === 'Row not found') {
-      return NextResponse.json({ error: errorMessage }, { status: 404 })
-    }
+    const classified = orchestrationErrorResponse(error)
+    if (classified) return classified
 
     logger.error(`[${requestId}] Error deleting row:`, error)
     return NextResponse.json({ error: 'Failed to delete row' }, { status: 500 })

apps/sim/app/api/table/import-async/route.ts

@@ -18,11 +18,11 @@ import {
   releaseJobClaim,
   sanitizeName,
   TABLE_LIMITS,
-  TableConflictError,
 } from '@/lib/table'
 import { runTableImport, type TableImportPayload } from '@/lib/table/import-runner'
 import { getUserSettings } from '@/lib/users/queries'
 import { getUserEntityPermissions } from '@/lib/workspaces/permissions/utils'
+import { orchestrationErrorResponse } from '@/app/api/table/utils'
 
 const logger = createLogger('TableImportAsync')
 
@@ -101,12 +101,8 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       requestId
     )
   } catch (error) {
-    if (error instanceof TableConflictError) {
-      return NextResponse.json({ error: error.message }, { status: 409 })
-    }
-    if (error instanceof Error && error.message.includes('maximum table limit')) {
-      return NextResponse.json({ error: error.message }, { status: 400 })
-    }
+    const classified = orchestrationErrorResponse(error)
+    if (classified) return classified
     throw error
   }
 

apps/sim/app/api/table/import-csv/route.test.ts

@@ -2,7 +2,6 @@
  * @vitest-environment node
  */
 import { hybridAuthMockFns, permissionsMock, permissionsMockFns } from '@sim/testing'
-import { getErrorMessage } from '@sim/utils/errors'
 import type { NextRequest } from 'next/server'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
@@ -32,6 +31,9 @@ vi.mock('@/lib/table/rows/service', () => ({
 vi.mock('@/lib/table/billing', () => ({ getWorkspaceTableLimits: mockGetLimits }))
 vi.mock('@/app/api/table/utils', async () => {
   const { NextResponse } = await import('next/server')
+  const { asOrchestrationError, statusForOrchestrationError } = await import(
+    '@/lib/core/orchestration/types'
+  )
   return {
     normalizeColumn: (column: unknown) => column,
     csvProxyBodyCapResponse: () => null,
@@ -40,16 +42,20 @@ vi.mock('@/app/api/table/utils', async () => {
         { error: error.message },
         { status: error.code === 'FILE_TOO_LARGE' ? 413 : 400 }
       ),
-    rowWriteErrorResponse: (error: unknown) => {
-      const message = getErrorMessage(error)
-      return message.includes('row limit')
-        ? NextResponse.json({ error: message }, { status: 400 })
+    orchestrationErrorResponse: (error: unknown) => {
+      const classified = asOrchestrationError(error)
+      return classified
+        ? NextResponse.json(
+            { error: classified.message },
+            { status: statusForOrchestrationError(classified.code) }
+          )
         : null
     },
   }
 })
 vi.mock('@/lib/workspaces/permissions/utils', () => permissionsMock)
 
+import { OrchestrationError } from '@/lib/core/orchestration/types'
 import { POST } from '@/app/api/table/import-csv/route'
 
 type Part =
@@ -184,7 +190,10 @@ describe('POST /api/table/import-csv', () => {
 
   it('returns 400 with the reason when an insert exceeds the plan row limit', async () => {
     mockBatchInsertRows.mockRejectedValueOnce(
-      new Error('This table has reached its row limit (1,000 rows) on your current plan.')
+      new OrchestrationError(
+        'validation',
+        'This table has reached its row limit (1,000 rows) on your current plan.'
+      )
     )
     const response = await POST(makeRequest(uploadParts(csvWithRows(250))))
     const data = await response.json()

apps/sim/app/api/table/import-csv/route.ts

@@ -1,6 +1,5 @@
 import type { Readable } from 'node:stream'
 import { createLogger } from '@sim/logger'
-import { toError } from '@sim/utils/errors'
 import { generateId } from '@sim/utils/id'
 import { type NextRequest, NextResponse } from 'next/server'
 import { csvExtensionSchema, csvImportFormSchema } from '@/lib/api/contracts/tables'
@@ -34,7 +33,7 @@ import {
   csvProxyBodyCapResponse,
   multipartErrorResponse,
   normalizeColumn,
-  rowWriteErrorResponse,
+  orchestrationErrorResponse,
 } from '@/app/api/table/utils'
 
 const logger = createLogger('TableImportCSV')
@@ -250,22 +249,12 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
 
     logger.error(`[${requestId}] CSV import failed:`, error)
 
-    // Row-write failures (e.g. the plan row-limit check) map to a 400 with the real reason.
-    const rowWriteError = rowWriteErrorResponse(error)
-    if (rowWriteError) return rowWriteError
+    // Every caller-fixable failure on this path — the plan row-limit check, the
+    // schema and CSV-shape validation, a name collision — arrives classified.
+    const classified = orchestrationErrorResponse(error)
+    if (classified) return classified
 
-    const message = toError(error).message
-    const isClientError =
-      message.includes('maximum table limit') ||
-      message.includes('CSV file has no') ||
-      message.includes('Invalid table name') ||
-      message.includes('Invalid schema') ||
-      message.includes('already exists')
-
-    return NextResponse.json(
-      { error: isClientError ? message : 'Failed to import CSV' },
-      { status: isClientError ? 400 : 500 }
-    )
+    return NextResponse.json({ error: 'Failed to import CSV' }, { status: 500 })
   } finally {
     fileStream?.destroy()
   }

apps/sim/app/api/table/route.ts

@@ -16,7 +16,7 @@ import {
   type TableScope,
 } from '@/lib/table'
 import { getUserEntityPermissions } from '@/lib/workspaces/permissions/utils'
-import { normalizeColumn } from '@/app/api/table/utils'
+import { normalizeColumn, orchestrationErrorResponse } from '@/app/api/table/utils'
 
 const logger = createLogger('TableAPI')
 
@@ -153,18 +153,8 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       },
     })
   } catch (error) {
-    if (error instanceof Error) {
-      if (error.message.includes('maximum table limit')) {
-        return NextResponse.json({ error: error.message }, { status: 403 })
-      }
-      if (
-        error.message.includes('Invalid table name') ||
-        error.message.includes('Invalid schema') ||
-        error.message.includes('already exists')
-      ) {
-        return NextResponse.json({ error: error.message }, { status: 400 })
-      }
-    }
+    const classified = orchestrationErrorResponse(error)
+    if (classified) return classified
 
     logger.error(`[${requestId}] Error creating table:`, error)
     return NextResponse.json({ error: 'Failed to create table' }, { status: 500 })