fix(api): report the lock kind on classified 423s too, not just thrown ones

The previous commit named the lock only where the rejection was thrown and
caught at the route boundary. Where it instead arrives as a classified
`errorCode: 'locked'` outcome — delete table, delete row, update column,
and the table mutations — the kind was dropped, so those 423s stayed
unactionable while their neighbours improved.

The orchestration results now carry `lock`, and a shared
`v2TableOrchestrationError` renders both arrival paths into the same
`{ code, message, details: { lock } }` body. `details` is omitted rather
than sent null when the kind is unknown, so a caller branching on it sees
absence instead of a phantom value.

Author: TheodoreSpeaks

apps/sim/app/api/v2/tables/[tableId]/columns/route.ts

@@ -19,12 +19,11 @@ import {
   v2CaughtOrchestrationError,
   v2Data,
   v2Error,
-  v2ErrorForOrchestration,
   v2RateLimitError,
   v2ValidationError,
   v2WorkspaceAccessError,
 } from '@/app/api/v2/lib/response'
-import { v2TableAccessError } from '@/app/api/v2/tables/utils'
+import { v2TableAccessError, v2TableOrchestrationError } from '@/app/api/v2/tables/utils'
 
 const logger = createLogger('V2TableColumnsAPI')
 
@@ -136,7 +135,7 @@ export const PATCH = withRouteHandler(async (request: NextRequest, context: Colu
       request,
     })
     if (!outcome.success || !outcome.table) {
-      return v2ErrorForOrchestration(outcome.errorCode, outcome.error ?? 'Failed to update column')
+      return v2TableOrchestrationError(outcome, 'Failed to update column')
     }
 
     return v2Data({ columns: outcome.table.schema.columns.map(normalizeColumn) }, { rateLimit })

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

@@ -20,12 +20,16 @@ import { v2ApiGateError } from '@/app/api/v2/lib/gate'
 import {
   v2Data,
   v2Error,
-  v2ErrorForOrchestration,
   v2RateLimitError,
   v2ValidationError,
   v2WorkspaceAccessError,
 } from '@/app/api/v2/lib/response'
-import { v2CsvBodyCapError, v2MultipartError, v2TableAccessError } from '@/app/api/v2/tables/utils'
+import {
+  v2CsvBodyCapError,
+  v2MultipartError,
+  v2TableAccessError,
+  v2TableOrchestrationError,
+} from '@/app/api/v2/tables/utils'
 
 const logger = createLogger('V2TableImportAPI')
 
@@ -116,14 +120,7 @@ export const POST = withRouteHandler(async (request: NextRequest, context: Table
     })
 
     if (!outcome.success || !outcome.data) {
-      // Naming the lock is the difference between an actionable 423 and one the
-      // caller has to guess at — there are four flags.
-      if (outcome.errorCode === 'locked') {
-        return v2Error('LOCKED', outcome.error ?? 'Table is locked', {
-          details: { lock: outcome.lock },
-        })
-      }
-      return v2ErrorForOrchestration(outcome.errorCode, outcome.error ?? 'Failed to import CSV')
+      return v2TableOrchestrationError(outcome, 'Failed to import CSV')
     }
 
     return v2Data(outcome.data, { rateLimit })

apps/sim/app/api/v2/tables/[tableId]/route.ts

@@ -28,12 +28,16 @@ import {
   v2CaughtOrchestrationError,
   v2Data,
   v2Error,
-  v2ErrorForOrchestration,
   v2RateLimitError,
   v2ValidationError,
   v2WorkspaceAccessError,
 } from '@/app/api/v2/lib/response'
-import { toApiTable, v2TableAccessError, v2TableLockError } from '@/app/api/v2/tables/utils'
+import {
+  toApiTable,
+  v2TableAccessError,
+  v2TableLockError,
+  v2TableOrchestrationError,
+} from '@/app/api/v2/tables/utils'
 
 const logger = createLogger('V2TableDetailAPI')
 
@@ -184,10 +188,7 @@ export const PATCH = withRouteHandler(async (request: NextRequest, context: Tabl
       if (outcome.success) {
         applied = true
       } else {
-        failure = v2ErrorForOrchestration(
-          outcome.errorCode,
-          outcome.error ?? 'Failed to update table locks'
-        )
+        failure = v2TableOrchestrationError(outcome, 'Failed to update table locks')
       }
     }
 
@@ -202,10 +203,7 @@ export const PATCH = withRouteHandler(async (request: NextRequest, context: Tabl
       if (outcome.success) {
         applied = true
       } else {
-        failure = v2ErrorForOrchestration(
-          outcome.errorCode,
-          outcome.error ?? 'Failed to rename table'
-        )
+        failure = v2TableOrchestrationError(outcome, 'Failed to rename table')
       }
     }
 
@@ -217,16 +215,16 @@ export const PATCH = withRouteHandler(async (request: NextRequest, context: Tabl
         requestId,
         request,
       })
-      if (outcome.success) applied = true
-      // The move re-asserts workspace and active state, so a miss means the
-      // table was archived between `checkAccess` and the write.
-      else
-        failure = v2ErrorForOrchestration(
-          outcome.errorCode,
-          outcome.errorCode === 'not_found'
-            ? 'Table not found'
-            : (outcome.error ?? 'Failed to move table')
+      if (outcome.success) {
+        applied = true
+      } else {
+        // The move re-asserts workspace and active state, so a miss means the
+        // table was archived between `checkAccess` and the write.
+        failure = v2TableOrchestrationError(
+          outcome.errorCode === 'not_found' ? { ...outcome, error: 'Table not found' } : outcome,
+          'Failed to move table'
         )
+      }
     }
 
     // Live-collab: tell open viewers the definition changed so they refetch.
@@ -285,7 +283,7 @@ export const DELETE = withRouteHandler(async (request: NextRequest, context: Tab
 
     const outcome = await performDeleteTable({ table: result.table, userId, requestId, request })
     if (!outcome.success) {
-      return v2ErrorForOrchestration(outcome.errorCode, outcome.error ?? 'Failed to delete table')
+      return v2TableOrchestrationError(outcome, 'Failed to delete table')
     }
 
     return v2Data({ id: tableId }, { rateLimit })

apps/sim/app/api/v2/tables/[tableId]/rows/[rowId]/route.test.ts

@@ -96,4 +96,27 @@ describe('DELETE /api/v2/tables/[tableId]/rows/[rowId]', () => {
     expect(res.status).toBe(status)
     expect((await res.json()).error.code).toBe(code)
   })
+
+  it('names the lock on a 423 that arrived as a classified outcome, not a throw', async () => {
+    mockPerformDeleteRow.mockResolvedValue({
+      success: false,
+      errorCode: 'locked',
+      error: 'Row deletes are locked for this table',
+      lock: 'delete',
+    })
+
+    const res = await callDelete()
+
+    expect(res.status).toBe(423)
+    expect((await res.json()).error.details).toEqual({ lock: 'delete' })
+  })
+
+  it('omits details entirely when the lock kind is unknown', async () => {
+    // A caller branching on `details.lock` should see absence, not a null.
+    mockPerformDeleteRow.mockResolvedValue({ success: false, errorCode: 'locked', error: 'nope' })
+
+    const res = await callDelete()
+
+    expect((await res.json()).error.details).toBeUndefined()
+  })
 })

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

@@ -23,12 +23,16 @@ import {
   v2CaughtOrchestrationError,
   v2Data,
   v2Error,
-  v2ErrorForOrchestration,
   v2RateLimitError,
   v2ValidationError,
   v2WorkspaceAccessError,
 } from '@/app/api/v2/lib/response'
-import { toApiRow, v2TableAccessError, v2TableLockError } from '@/app/api/v2/tables/utils'
+import {
+  toApiRow,
+  v2TableAccessError,
+  v2TableLockError,
+  v2TableOrchestrationError,
+} from '@/app/api/v2/tables/utils'
 
 const logger = createLogger('V2TableRowAPI')
 
@@ -209,7 +213,7 @@ export const DELETE = withRouteHandler(async (request: NextRequest, context: Row
 
     const outcome = await performDeleteTableRow({ table: result.table, rowId, requestId })
     if (!outcome.success) {
-      return v2ErrorForOrchestration(outcome.errorCode, outcome.error ?? 'Failed to delete row')
+      return v2TableOrchestrationError(outcome, 'Failed to delete row')
     }
 
     // v2 mirrors the bulk delete shape: always returns `deletedRowIds`.

apps/sim/app/api/v2/tables/utils.ts

@@ -1,4 +1,5 @@
 import type { NextResponse } from 'next/server'
+import type { OrchestrationErrorCode } from '@/lib/core/orchestration/types'
 import type { MultipartError } from '@/lib/core/utils/multipart'
 import type { RowData, TableDefinition, TablePredicate, TableSchema } from '@/lib/table'
 import { getColumnId } from '@/lib/table/column-keys'
@@ -9,15 +10,15 @@ import {
   validateStoragePredicate,
 } from '@/lib/table/query-builder/validate'
 import { predicateToStorage } from '@/lib/table/select-values'
-import type { Filter } from '@/lib/table/types'
+import type { Filter, TableLockKind } from '@/lib/table/types'
 import type { TableView } from '@/lib/table/views/service'
 import {
   CSV_IMPORT_PROXY_BODY_CAP_BYTES,
   normalizeColumn,
   rootErrorMessage,
   rowWriteErrorResponse,
 } from '@/app/api/table/utils'
-import { v2Error } from '@/app/api/v2/lib/response'
+import { v2Error, v2ErrorForOrchestration } from '@/app/api/v2/lib/response'
 
 /**
  * Shared serialization + error helpers for the v2 tables surface. Every v2
@@ -178,6 +179,31 @@ export function v2TableLockError(error: unknown): NextResponse | null {
   return null
 }
 
+/**
+ * Renders a `lib/table/orchestration` failure in the v2 envelope, naming the
+ * lock when one caused it.
+ *
+ * A lock rejection reaches a route two different ways — thrown and caught at
+ * the boundary ({@link v2TableLockError}), or returned as a classified
+ * `errorCode: 'locked'` outcome — and both must produce the same body. Plain
+ * {@link v2ErrorForOrchestration} cannot, because the `lock` kind lives on the
+ * outcome rather than the code, so every table route that renders an
+ * orchestration result goes through this instead.
+ */
+export function v2TableOrchestrationError(
+  outcome: { errorCode?: OrchestrationErrorCode; error?: string; lock?: TableLockKind },
+  fallback: string
+): NextResponse {
+  if (outcome.errorCode === 'locked') {
+    return v2Error('LOCKED', outcome.error ?? fallback, {
+      // Omitted rather than sent as null when the kind is unknown — a caller
+      // branching on `details.lock` should see absence, not a phantom value.
+      ...(outcome.lock ? { details: { lock: outcome.lock } } : {}),
+    })
+  }
+  return v2ErrorForOrchestration(outcome.errorCode, outcome.error ?? fallback)
+}
+
 /**
  * Maps a known user-facing row-write failure (schema/size/unique/limit) to a v2
  * `BAD_REQUEST`, reusing v1's {@link rowWriteErrorResponse} classifier as the

apps/sim/lib/table/orchestration/columns.ts

@@ -18,7 +18,7 @@ import {
 import { isSupportedCurrencyCode } from '@/lib/table/currency'
 import { TableLockedError } from '@/lib/table/mutation-locks'
 import { normalizeSelectOptionsInput } from '@/lib/table/select-options'
-import type { ColumnType, SelectOption, TableDefinition } from '@/lib/table/types'
+import type { ColumnType, SelectOption, TableDefinition, TableLockKind } from '@/lib/table/types'
 
 const logger = createLogger('TableColumnOrchestration')
 
@@ -45,12 +45,14 @@ export interface PerformUpdateTableColumnResult {
   success: boolean
   error?: string
   errorCode?: OrchestrationErrorCode
+  /** Which lock rejected the write. Set only when `errorCode` is `'locked'`. */
+  lock?: TableLockKind
   table?: TableDefinition
 }
 
 function classify(error: unknown): PerformUpdateTableColumnResult {
   if (error instanceof TableLockedError) {
-    return { success: false, error: error.message, errorCode: 'locked' }
+    return { success: false, error: error.message, errorCode: 'locked', lock: error.lock }
   }
   if (error instanceof OrchestrationError) {
     return { success: false, error: error.message, errorCode: error.code }

apps/sim/lib/table/orchestration/tables.test.ts

@@ -85,7 +85,7 @@ describe('performDeleteTable', () => {
 
     const result = await performDeleteTable({ table: TABLE, userId: 'user-1' })
 
-    expect(result).toMatchObject({ success: false, errorCode: 'locked' })
+    expect(result).toMatchObject({ success: false, errorCode: 'locked', lock: 'delete' })
     expect(mockCaptureServerEvent).not.toHaveBeenCalled()
   })
 })
@@ -129,7 +129,10 @@ describe('performDeleteTableRow', () => {
   it('classifies a delete lock as locked', async () => {
     mockDeleteRow.mockRejectedValue(new TableLockedError('delete'))
 
-    expect((await performDeleteTableRow({ table: TABLE, rowId: 'row-1' })).errorCode).toBe('locked')
+    const rowResult = await performDeleteTableRow({ table: TABLE, rowId: 'row-1' })
+    expect(rowResult.errorCode).toBe('locked')
+    // The kind rides along so the route can name which flag to clear.
+    expect(rowResult.lock).toBe('delete')
   })
 
   it('classifies a missing row as not_found', async () => {

apps/sim/lib/table/orchestration/tables.ts

@@ -15,6 +15,7 @@ import {
   TABLE_LOCK_FLAGS,
   TABLE_LOCK_KINDS,
   type TableDefinition,
+  type TableLockKind,
   type TableLocks,
 } from '@/lib/table/types'
 
@@ -32,6 +33,8 @@ export interface PerformDeleteTableResult {
   success: boolean
   error?: string
   errorCode?: OrchestrationErrorCode
+  /** Which lock rejected the write. Set only when `errorCode` is `'locked'`. */
+  lock?: TableLockKind
 }
 
 /**
@@ -54,7 +57,7 @@ export async function performDeleteTable(
     ;({ archived } = await deleteTable(table.id, requestId))
   } catch (error) {
     if (error instanceof TableLockedError) {
-      return { success: false, error: error.message, errorCode: 'locked' }
+      return { success: false, error: error.message, errorCode: 'locked', lock: error.lock }
     }
     if (error instanceof OrchestrationError) {
       return { success: false, error: error.message, errorCode: error.code }
@@ -98,6 +101,8 @@ export interface PerformDeleteTableRowResult {
   success: boolean
   error?: string
   errorCode?: OrchestrationErrorCode
+  /** Which lock rejected the write. Set only when `errorCode` is `'locked'`. */
+  lock?: TableLockKind
 }
 
 /**
@@ -116,7 +121,7 @@ export async function performDeleteTableRow(
     return { success: true }
   } catch (error) {
     if (error instanceof TableLockedError) {
-      return { success: false, error: error.message, errorCode: 'locked' }
+      return { success: false, error: error.message, errorCode: 'locked', lock: error.lock }
     }
     if (error instanceof OrchestrationError) {
       return { success: false, error: error.message, errorCode: error.code }
@@ -139,12 +144,19 @@ export interface PerformTableMutationResult {
   success: boolean
   error?: string
   errorCode?: OrchestrationErrorCode
+  /** Which lock rejected the write. Set only when `errorCode` is `'locked'`. */
+  lock?: TableLockKind
   table?: TableDefinition
 }
 
 function classifyTableMutation(error: unknown, requestId: string, tableId: string) {
   if (error instanceof TableLockedError) {
-    return { success: false as const, error: error.message, errorCode: 'locked' as const }
+    return {
+      success: false as const,
+      error: error.message,
+      errorCode: 'locked' as const,
+      lock: error.lock,
+    }
   }
   // `TableConflictError` is an `OrchestrationError('conflict')`, so a duplicate
   // rename reaches 409 through this branch — by class, not by the message