fix(api): collapse the internal error envelope and restore requestId

waleedlatif1 · waleedlatif1 · commit ee17317e32c7 · 2026-08-11T19:15:55.000-07:00
The builders shipped two internal error envelopes: internalOrchestrationErrorPolicy
emitted { success: false, error } while internalPlainOrchestrationErrorPolicy
emitted { error }. That split approximated pre-builder behavior, where the shape
depended on which branch failed - guard clauses returned { error } and a route's
terminal try/catch returned { success: false, error }. A per-route policy cannot
express a per-branch rule, so the two disagreed on the same status across families.

Collapse to the bare { error } shape. It is what messageFromErrorBody reads on the
client and what most migrated routes already emitted. requestJson throws
ApiClientError for any non-2xx, so no typed client ever observes the discriminator.
success: true on success bodies is a separate contract and is untouched.

Also restore requestId to internal error bodies. withRouteHandler stamps it on the
bodies it generates, but the builder overrides dropped it, leaving it only on the
x-request-id header - invisible when a user pastes an error out of the UI. It is now
applied at the createJsonErrorResponse chokepoint and in both wrapper overrides, and
is omitted when there is no active request scope.
diff --git a/apps/sim/app/api/audit-logs/route.ts b/apps/sim/app/api/audit-logs/route.ts
@@ -1,7 +1,7 @@
 import { listAuditLogsContract } from '@/lib/api/contracts/audit-logs'
 import {
   defineInternalJsonRoute,
-  internalPlainOrchestrationErrorPolicy,
+  internalOrchestrationErrorPolicy,
   internalRateLimits,
   internalSessionAuth,
 } from '@/lib/api/server/routes'
@@ -18,7 +18,7 @@ export const GET = defineInternalJsonRoute({
   rateLimit: internalRateLimits.none({
     reason: 'Existing authenticated audit-log settings read has no request-rate policy',
   }),
-  errorPolicy: internalPlainOrchestrationErrorPolicy,
+  errorPolicy: internalOrchestrationErrorPolicy,
   mapInput: ({ query }) => ({
     organizationId: query.organizationId,
     includeDeparted: query.includeDeparted,
diff --git a/apps/sim/app/api/table/[tableId]/exports/route.ts b/apps/sim/app/api/table/[tableId]/exports/route.ts
@@ -1,7 +1,7 @@
 import { createTableExportResourceContract } from '@/lib/api/contracts/table-transfers'
 import {
   defineInternalJsonRoute,
-  internalPlainOrchestrationErrorPolicy,
+  internalOrchestrationErrorPolicy,
   internalRateLimits,
 } from '@/lib/api/server/routes'
 import { internalTableSessionOrExecutorAuth } from '@/lib/table/api'
@@ -16,7 +16,7 @@ export const POST = defineInternalJsonRoute({
   rateLimit: internalRateLimits.none({
     reason: 'Existing authenticated table export creation has no request-rate policy',
   }),
-  errorPolicy: internalPlainOrchestrationErrorPolicy,
+  errorPolicy: internalOrchestrationErrorPolicy,
   mapInput: ({ params, body }) => ({
     tableId: params.tableId,
     workspaceId: body.workspaceId,
diff --git a/apps/sim/app/api/table/[tableId]/groups/route.test.ts b/apps/sim/app/api/table/[tableId]/groups/route.test.ts
@@ -36,7 +36,7 @@ vi.mock('@/lib/api/server/routes', () => ({
   },
   extendInternalErrorPolicy: vi.fn(() => ({ kind: 'table' })),
   internalErrorResponse: vi.fn(),
-  internalPlainOrchestrationErrorPolicy: { kind: 'plain' },
+  internalOrchestrationErrorPolicy: { kind: 'plain' },
   internalRateLimits: {
     none: ({ reason }: { reason: string }) => ({ kind: 'none', reason }),
   },
diff --git a/apps/sim/app/api/table/[tableId]/groups/route.ts b/apps/sim/app/api/table/[tableId]/groups/route.ts
@@ -7,7 +7,7 @@ import {
   defineInternalJsonRoute,
   extendInternalErrorPolicy,
   internalErrorResponse,
-  internalPlainOrchestrationErrorPolicy,
+  internalOrchestrationErrorPolicy,
   internalRateLimits,
 } from '@/lib/api/server/routes'
 import { internalTableSessionOrExecutorAuth } from '@/lib/table/api'
@@ -21,7 +21,7 @@ import { TableLockedError } from '@/lib/table/mutation-locks'
 import type { TableDefinition } from '@/lib/table/types'
 import { normalizeColumn } from '@/app/api/table/utils'
 
-const errorPolicy = extendInternalErrorPolicy(internalPlainOrchestrationErrorPolicy, (error) =>
+const errorPolicy = extendInternalErrorPolicy(internalOrchestrationErrorPolicy, (error) =>
   error instanceof TableLockedError
     ? internalErrorResponse(423, { error: error.message, lock: error.lock })
     : null
diff --git a/apps/sim/app/api/table/exports/[exportId]/download/route.ts b/apps/sim/app/api/table/exports/[exportId]/download/route.ts
@@ -1,7 +1,7 @@
 import { downloadTableExportResourceContract } from '@/lib/api/contracts/table-transfers'
 import {
   defineInternalJsonRoute,
-  internalPlainOrchestrationErrorPolicy,
+  internalOrchestrationErrorPolicy,
   internalRateLimits,
 } from '@/lib/api/server/routes'
 import { internalTableSessionOrExecutorAuth } from '@/lib/table/api'
@@ -15,7 +15,7 @@ export const GET = defineInternalJsonRoute({
   rateLimit: internalRateLimits.none({
     reason: 'Existing authenticated table export download signing has no request-rate policy',
   }),
-  errorPolicy: internalPlainOrchestrationErrorPolicy,
+  errorPolicy: internalOrchestrationErrorPolicy,
   mapInput: ({ params, query }) => ({
     exportId: params.exportId,
     workspaceId: query.workspaceId,
diff --git a/apps/sim/app/api/table/exports/[exportId]/route.ts b/apps/sim/app/api/table/exports/[exportId]/route.ts
@@ -4,7 +4,7 @@ import {
 } from '@/lib/api/contracts/table-transfers'
 import {
   defineInternalJsonRoute,
-  internalPlainOrchestrationErrorPolicy,
+  internalOrchestrationErrorPolicy,
   internalRateLimits,
 } from '@/lib/api/server/routes'
 import { internalTableSessionOrExecutorAuth } from '@/lib/table/api'
@@ -21,7 +21,7 @@ export const GET = defineInternalJsonRoute({
   auth: internalTableSessionOrExecutorAuth,
   operation: tableOperations.readExport,
   rateLimit,
-  errorPolicy: internalPlainOrchestrationErrorPolicy,
+  errorPolicy: internalOrchestrationErrorPolicy,
   mapInput: ({ params, query }) => ({
     exportId: params.exportId,
     workspaceId: query.workspaceId,
@@ -35,7 +35,7 @@ export const DELETE = defineInternalJsonRoute({
   auth: internalTableSessionOrExecutorAuth,
   operation: tableOperations.cancelExport,
   rateLimit,
-  errorPolicy: internalPlainOrchestrationErrorPolicy,
+  errorPolicy: internalOrchestrationErrorPolicy,
   mapInput: ({ params, query }) => ({
     exportId: params.exportId,
     workspaceId: query.workspaceId,
diff --git a/apps/sim/app/api/table/imports/[importId]/complete/route.ts b/apps/sim/app/api/table/imports/[importId]/complete/route.ts
@@ -1,7 +1,7 @@
 import { completeTableImportResourceContract } from '@/lib/api/contracts/table-transfers'
 import {
   defineInternalJsonRoute,
-  internalPlainOrchestrationErrorPolicy,
+  internalOrchestrationErrorPolicy,
   internalRateLimits,
 } from '@/lib/api/server/routes'
 import { internalTableSessionOrExecutorAuth } from '@/lib/table/api'
@@ -16,7 +16,7 @@ export const POST = defineInternalJsonRoute({
   rateLimit: internalRateLimits.none({
     reason: 'Existing authenticated table import completion has no request-rate policy',
   }),
-  errorPolicy: internalPlainOrchestrationErrorPolicy,
+  errorPolicy: internalOrchestrationErrorPolicy,
   mapInput: ({ params, query, headers }) => ({
     importId: params.importId,
     workspaceId: query.workspaceId,
diff --git a/apps/sim/app/api/table/imports/[importId]/parts/route.ts b/apps/sim/app/api/table/imports/[importId]/parts/route.ts
@@ -1,7 +1,7 @@
 import { createTableImportPartUrlsContract } from '@/lib/api/contracts/table-transfers'
 import {
   defineInternalJsonRoute,
-  internalPlainOrchestrationErrorPolicy,
+  internalOrchestrationErrorPolicy,
   internalRateLimits,
 } from '@/lib/api/server/routes'
 import { internalTableSessionOrExecutorAuth } from '@/lib/table/api'
@@ -15,7 +15,7 @@ export const POST = defineInternalJsonRoute({
   rateLimit: internalRateLimits.none({
     reason: 'Existing authenticated table import part signing has no request-rate policy',
   }),
-  errorPolicy: internalPlainOrchestrationErrorPolicy,
+  errorPolicy: internalOrchestrationErrorPolicy,
   mapInput: ({ params, query, headers, body }) => ({
     importId: params.importId,
     workspaceId: query.workspaceId,
diff --git a/apps/sim/app/api/table/imports/[importId]/route.ts b/apps/sim/app/api/table/imports/[importId]/route.ts
@@ -4,7 +4,7 @@ import {
 } from '@/lib/api/contracts/table-transfers'
 import {
   defineInternalJsonRoute,
-  internalPlainOrchestrationErrorPolicy,
+  internalOrchestrationErrorPolicy,
   internalRateLimits,
 } from '@/lib/api/server/routes'
 import { internalTableSessionOrExecutorAuth } from '@/lib/table/api'
@@ -21,7 +21,7 @@ export const GET = defineInternalJsonRoute({
   auth: internalTableSessionOrExecutorAuth,
   operation: tableOperations.readImport,
   rateLimit,
-  errorPolicy: internalPlainOrchestrationErrorPolicy,
+  errorPolicy: internalOrchestrationErrorPolicy,
   mapInput: ({ params, query }) => ({
     importId: params.importId,
     workspaceId: query.workspaceId,
@@ -35,7 +35,7 @@ export const DELETE = defineInternalJsonRoute({
   auth: internalTableSessionOrExecutorAuth,
   operation: tableOperations.cancelImport,
   rateLimit,
-  errorPolicy: internalPlainOrchestrationErrorPolicy,
+  errorPolicy: internalOrchestrationErrorPolicy,
   mapInput: ({ params, query, headers }) => ({
     importId: params.importId,
     workspaceId: query.workspaceId,
diff --git a/apps/sim/app/api/table/imports/route.ts b/apps/sim/app/api/table/imports/route.ts
@@ -1,7 +1,7 @@
 import { createTableImportResourceContract } from '@/lib/api/contracts/table-transfers'
 import {
   defineInternalJsonRoute,
-  internalPlainOrchestrationErrorPolicy,
+  internalOrchestrationErrorPolicy,
   internalRateLimits,
 } from '@/lib/api/server/routes'
 import { internalTableSessionOrExecutorAuth } from '@/lib/table/api'
@@ -16,7 +16,7 @@ export const POST = defineInternalJsonRoute({
   rateLimit: internalRateLimits.none({
     reason: 'Existing authenticated table import creation has no request-rate policy',
   }),
-  errorPolicy: internalPlainOrchestrationErrorPolicy,
+  errorPolicy: internalOrchestrationErrorPolicy,
   mapInput: ({ body }) => ({ body }),
   useCase: createTableImportUseCase,
   present: ({ import: created }) => ({ data: toV2CreateTableImport(created) }),
diff --git a/apps/sim/app/api/table/table-transfer-routes.test.ts b/apps/sim/app/api/table/table-transfer-routes.test.ts
@@ -35,7 +35,7 @@ vi.mock('@/lib/api/server/routes', () => ({
     mocks.definitions.push(definition)
     return vi.fn()
   },
-  internalPlainOrchestrationErrorPolicy: { kind: 'plain' },
+  internalOrchestrationErrorPolicy: { kind: 'plain' },
   internalRateLimits: {
     none: ({ reason }: { reason: string }) => ({ kind: 'none', reason }),
   },
diff --git a/apps/sim/app/api/workflows/[id]/deployed/route.ts b/apps/sim/app/api/workflows/[id]/deployed/route.ts
@@ -5,7 +5,7 @@ import {
 } from '@/lib/api/contracts/deployments'
 import {
   defineInternalJsonRoute,
-  internalPlainOrchestrationErrorPolicy,
+  internalOrchestrationErrorPolicy,
   internalRateLimits,
 } from '@/lib/api/server/routes'
 import { internalWorkflowSessionOrExecutorAuth } from '@/lib/workflows/api'
@@ -23,7 +23,7 @@ export const GET = defineInternalJsonRoute({
   rateLimit: internalRateLimits.none({
     reason: 'Preserve existing internal workflow read behavior',
   }),
-  errorPolicy: internalPlainOrchestrationErrorPolicy,
+  errorPolicy: internalOrchestrationErrorPolicy,
   mapInput: ({ params }) => ({ workflowId: params.id, state: 'deployed' as const }),
   useCase: readWorkflowDefinition,
   present: ({ state }) => ({
diff --git a/apps/sim/app/api/workflows/[id]/route.test.ts b/apps/sim/app/api/workflows/[id]/route.test.ts
@@ -20,7 +20,7 @@ vi.mock('@/lib/api/server', () => ({ parseRequest: mocks.parseRequest }))
 vi.mock('@/lib/api/server/routes', () => ({
   defineInternalJsonRoute: mocks.defineRoute,
   InternalUnauthenticatedError: class InternalUnauthenticatedError extends Error {},
-  internalPlainOrchestrationErrorPolicy: { kind: 'plain-orchestration' },
+  internalOrchestrationErrorPolicy: { kind: 'plain-orchestration' },
   internalRateLimits: { none: vi.fn(() => ({ kind: 'none' })) },
 }))
 
diff --git a/apps/sim/app/api/workflows/[id]/route.ts b/apps/sim/app/api/workflows/[id]/route.ts
@@ -12,7 +12,7 @@ import { parseRequest } from '@/lib/api/server'
 import {
   defineInternalJsonRoute,
   InternalUnauthenticatedError,
-  internalPlainOrchestrationErrorPolicy,
+  internalOrchestrationErrorPolicy,
   internalRateLimits,
 } from '@/lib/api/server/routes'
 import { asOrchestrationError, statusForOrchestrationError } from '@/lib/core/orchestration/types'
@@ -37,7 +37,7 @@ export const GET = defineInternalJsonRoute({
   auth: internalWorkflowReadAuth,
   operation: readWorkflowDefinition.operation,
   rateLimit: workflowInternalRateLimit,
-  errorPolicy: internalPlainOrchestrationErrorPolicy,
+  errorPolicy: internalOrchestrationErrorPolicy,
   mapInput: ({ params }) => ({ workflowId: params.id, state: 'draft' as const }),
   useCase: readWorkflowDefinition,
   present: ({ workflow: workflowData, state }) => {
@@ -82,7 +82,7 @@ export const DELETE = defineInternalJsonRoute({
   auth: internalWorkflowSessionOrExecutorAuth,
   operation: deleteWorkflow.operation,
   rateLimit: workflowInternalRateLimit,
-  errorPolicy: internalPlainOrchestrationErrorPolicy,
+  errorPolicy: internalOrchestrationErrorPolicy,
   mapInput: ({ params }) => ({ workflowId: params.id }),
   useCase: deleteWorkflow,
   present: () => ({ success: true as const }),
diff --git a/apps/sim/app/api/workspaces/[id]/files/[fileId]/content/route.test.ts b/apps/sim/app/api/workspaces/[id]/files/[fileId]/content/route.test.ts
@@ -143,7 +143,6 @@ describe('PUT /api/workspaces/[id]/files/[fileId]/content', () => {
 
     expect(response.status).toBe(402)
     await expect(response.json()).resolves.toEqual({
-      success: false,
       error: 'Storage limit exceeded',
     })
   })
diff --git a/apps/sim/app/api/workspaces/[id]/files/[fileId]/csv-preview/route.ts b/apps/sim/app/api/workspaces/[id]/files/[fileId]/csv-preview/route.ts
@@ -14,7 +14,7 @@ export const GET = defineInternalJsonRoute({
   auth: internalSessionOrExecutorAuth,
   operation: csvPreviewWorkspaceFile.operation,
   rateLimit: internalRateLimits.none({ reason: 'Preserve existing internal CSV preview behavior' }),
-  errorPolicy: internalFileErrorPolicies.plain,
+  errorPolicy: internalFileErrorPolicies.default,
   mapInput: ({ params, query }) => ({
     fileId: params.fileId,
     assertedWorkspaceId: params.id,
diff --git a/apps/sim/app/api/workspaces/[id]/files/[fileId]/route.test.ts b/apps/sim/app/api/workspaces/[id]/files/[fileId]/route.test.ts
@@ -126,7 +126,6 @@ describe('PATCH /api/workspaces/[id]/files/[fileId]', () => {
 
     expect(response.status).toBe(403)
     expect(await response.json()).toEqual({
-      success: false,
       error: 'Insufficient workspace permissions',
     })
     expect(mocks.captureServerEvent).not.toHaveBeenCalled()
@@ -139,7 +138,6 @@ describe('PATCH /api/workspaces/[id]/files/[fileId]', () => {
 
     expect(response.status).toBe(500)
     expect(await response.json()).toEqual({
-      success: false,
       error: 'Internal server error',
     })
   })
diff --git a/apps/sim/app/api/workspaces/[id]/files/[fileId]/share/route.test.ts b/apps/sim/app/api/workspaces/[id]/files/[fileId]/share/route.test.ts
@@ -96,7 +96,7 @@ describe('/api/workspaces/[id]/files/[fileId]/share', () => {
     const response = await GET(getRequest(), context)
 
     expect(response.status).toBe(403)
-    expect(await response.json()).toEqual({ success: false, error: 'Access denied' })
+    expect(await response.json()).toEqual({ error: 'Access denied' })
   })
 
   it('renders resource absence as 404', async () => {
@@ -142,7 +142,7 @@ describe('/api/workspaces/[id]/files/[fileId]/share', () => {
     const response = await PUT(putRequest({ isActive: true }), context)
 
     expect(response.status).toBe(400)
-    expect(await response.json()).toEqual({ success: false, error: 'Password is required' })
+    expect(await response.json()).toEqual({ error: 'Password is required' })
   })
 
   it('preserves the internal caller-supplied token field for compatibility', async () => {
diff --git a/apps/sim/app/api/workspaces/[id]/files/folders/[folderId]/route.test.ts b/apps/sim/app/api/workspaces/[id]/files/folders/[folderId]/route.test.ts
@@ -112,7 +112,6 @@ describe('/api/workspaces/[id]/files/folders/[folderId]', () => {
 
     expect(response.status).toBe(409)
     await expect(response.json()).resolves.toEqual({
-      success: false,
       error: 'A folder named "Reports" already exists in this location',
     })
     expect(mocks.captureServerEvent).not.toHaveBeenCalled()
@@ -140,7 +139,6 @@ describe('/api/workspaces/[id]/files/folders/[folderId]', () => {
 
     expect(response.status).toBe(404)
     expect(await response.json()).toEqual({
-      success: false,
       error: `Workspace file items not found (folders: ${FOLDER_ID})`,
     })
     expect(mocks.captureServerEvent).not.toHaveBeenCalled()
diff --git a/apps/sim/app/api/workspaces/[id]/files/folders/route.test.ts b/apps/sim/app/api/workspaces/[id]/files/folders/route.test.ts
@@ -113,7 +113,6 @@ describe('/api/workspaces/[id]/files/folders', () => {
 
     expect(response.status).toBe(409)
     await expect(response.json()).resolves.toEqual({
-      success: false,
       error: 'A folder named "Reports" already exists in this location',
     })
     expect(mocks.captureServerEvent).not.toHaveBeenCalled()
diff --git a/apps/sim/app/api/workspaces/[id]/files/move/route.test.ts b/apps/sim/app/api/workspaces/[id]/files/move/route.test.ts
@@ -83,7 +83,6 @@ describe('/api/workspaces/[id]/files/move', () => {
 
     expect(response.status).toBe(409)
     await expect(response.json()).resolves.toEqual({
-      success: false,
       error: 'A file named "report.csv" already exists in the destination folder',
     })
     expect(mocks.captureServerEvent).not.toHaveBeenCalled()
diff --git a/apps/sim/app/api/workspaces/[id]/files/route.test.ts b/apps/sim/app/api/workspaces/[id]/files/route.test.ts
@@ -146,13 +146,12 @@ describe('/api/workspaces/[id]/files', () => {
     mocks.createFile.mockRejectedValueOnce(new OrchestrationError('conflict', 'Name exists'))
     const conflict = await POST(createRequest({ name: 'notes.md' }), context)
     expect(conflict.status).toBe(409)
-    expect(await conflict.json()).toEqual({ success: false, error: 'Name exists' })
+    expect(await conflict.json()).toEqual({ error: 'Name exists' })
 
     mocks.createFile.mockRejectedValueOnce(new Error('database details'))
     const unexpected = await POST(createRequest({ name: 'notes.md' }), context)
     expect(unexpected.status).toBe(500)
     expect(await unexpected.json()).toEqual({
-      success: false,
       error: 'Internal server error',
     })
   })
diff --git a/apps/sim/lib/api/server/routes/index.ts b/apps/sim/lib/api/server/routes/index.ts
@@ -9,7 +9,6 @@ export {
   internalErrorResponse,
   internalJsonPresenters,
   internalOrchestrationErrorPolicy,
-  internalPlainOrchestrationErrorPolicy,
   internalRateLimits,
   internalSessionAuth,
 } from '@/lib/api/server/routes/internal-json-route'
diff --git a/apps/sim/lib/api/server/routes/internal-binary-route.ts b/apps/sim/lib/api/server/routes/internal-binary-route.ts
@@ -7,6 +7,7 @@ import {
   InternalUnauthenticatedError,
   type internalSessionAuth,
 } from '@/lib/api/server/routes/internal-json-route'
+import { withRequestId } from '@/lib/api/server/routes/request-id'
 import type {
   BinaryApiRouteContract,
   BinaryResponseDescriptor,
@@ -111,18 +112,18 @@ export function defineInternalBinaryRoute<
       }
     },
     {
-      typedErrorResponse: ({ error, status }) =>
-        NextResponse.json({ error: error.message }, { status }),
-      unhandledErrorResponse: () =>
-        NextResponse.json({ error: 'Internal server error' }, { status: 500 }),
+      typedErrorResponse: ({ error, status, requestId }) =>
+        NextResponse.json({ error: error.message, requestId }, { status }),
+      unhandledErrorResponse: ({ requestId }) =>
+        NextResponse.json({ error: 'Internal server error', requestId }, { status: 500 }),
     }
   )
 
   return async (request, context) => wrapped(request, context)
 }
 
 function createJsonErrorResponse(descriptor: JsonErrorResponseDescriptor): NextResponse {
-  return NextResponse.json(descriptor.body, {
+  return NextResponse.json(withRequestId(descriptor.body), {
     status: descriptor.status,
     headers: descriptor.headers,
   })
diff --git a/apps/sim/lib/api/server/routes/internal-json-route.test.ts b/apps/sim/lib/api/server/routes/internal-json-route.test.ts
diff --git a/apps/sim/lib/api/server/routes/internal-json-route.ts b/apps/sim/lib/api/server/routes/internal-json-route.ts
diff --git a/apps/sim/lib/api/server/routes/request-id.test.ts b/apps/sim/lib/api/server/routes/request-id.test.ts
diff --git a/apps/sim/lib/api/server/routes/request-id.ts b/apps/sim/lib/api/server/routes/request-id.ts
diff --git a/apps/sim/lib/knowledge/api/route-policies.ts b/apps/sim/lib/knowledge/api/route-policies.ts
diff --git a/apps/sim/lib/table/api/route-policies.test.ts b/apps/sim/lib/table/api/route-policies.test.ts
diff --git a/apps/sim/lib/workspace-files/api/internal-error-policies.test.ts b/apps/sim/lib/workspace-files/api/internal-error-policies.test.ts
diff --git a/apps/sim/lib/workspace-files/api/internal-error-policies.ts b/apps/sim/lib/workspace-files/api/internal-error-policies.ts
