refactor(v2): derive the body 413 from the contract in every document

Two mechanisms encoded one rule. `withRequestBodyErrors` derived the 413 from
`route.contract.body` for the tables document, while the resources document
hand-picked RESOURCE_BODY_ERRORS / RESOURCE_CONFLICT_BODY_ERRORS at nine
sites. The cross-document sweep caught drift, but only after the fact: a new
body operation that forgot the _BODY_ variant published a reachable 413
nowhere until a test failed.

Hoists the mapper to openapi/shared.ts and applies it in both documents, so
the rule is derived rather than remembered. The two hand-picked sets and
their shared TSDoc are gone.

Regenerating all seven specs produces zero drift, which is the proof the two
mechanisms were computing the same thing.

Author: waleedlatif1

apps/sim/lib/api/contracts/v2/openapi/resources.ts

@@ -21,15 +21,14 @@ import {
   FULL_SET_LIST,
   HEAD_MIRRORS_GET,
   RATE_LIMIT_HEADERS,
-  RESOURCE_BODY_ERRORS,
-  RESOURCE_CONFLICT_BODY_ERRORS,
   RESOURCE_CONFLICT_ERRORS,
   RESOURCE_ERRORS,
   V2_API_KEY_SECURITY,
   V2_API_KEY_SECURITY_SCHEMES,
   V2_COMMON_HEADERS,
   V2_ERROR_SCHEMA,
   WORKSPACE_API_KEY_DENIED,
+  withRequestBodyErrors,
 } from '@/lib/api/contracts/v2/openapi/shared'
 import {
   v2DeleteSecretContract,
@@ -214,7 +213,7 @@ function resourceOperation(
   }
 }
 
-const routes = [
+const declaredRoutes = [
   defineOpenApiRoute(
     v2GetWorkspaceContract,
     resourceOperation('Workspaces', {
@@ -307,7 +306,7 @@ const routes = [
       summary: 'Create MCP Server',
       description:
         'Register an MCP server in a workspace. The endpoint URL is the server identity, so a URL already registered here is a `409` — reconfigure that server with `PATCH /api/v2/mcp-servers/{id}` instead. Registration never connects to the endpoint: the server comes back `disconnected` and stays unavailable until `GET /api/v2/mcp-servers/{id}/tools` succeeds.',
-      errors: RESOURCE_CONFLICT_BODY_ERRORS,
+      errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The MCP server was registered.' },
     }),
     {
@@ -375,7 +374,7 @@ const routes = [
       summary: 'Update MCP Server',
       description:
         'Update the supplied MCP server fields. Omitted fields are retained, except where a field says otherwise. Any change that invalidates authentication revokes the stored OAuth grant, resets `connectionStatus` to `disconnected`, and clears `lastConnected` and `lastError`, so the server must be rediscovered.',
-      errors: RESOURCE_BODY_ERRORS,
+      errors: RESOURCE_ERRORS,
       success: { description: 'The updated MCP server.' },
     }),
     {
@@ -497,7 +496,7 @@ const routes = [
       operationId: 'createSkill',
       summary: 'Create Skill',
       description: `Create one skill in a workspace. Its kebab-case name must be unique and cannot be reserved by a built-in skill. ${WORKSPACE_API_KEY_DENIED}`,
-      errors: RESOURCE_CONFLICT_BODY_ERRORS,
+      errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The skill was created.' },
     }),
     {
@@ -563,7 +562,7 @@ const routes = [
       operationId: 'updateSkill',
       summary: 'Update Skill',
       description: `Update the supplied fields on a workspace skill. Omitted fields retain their stored values. Built-in skills are read-only. ${WORKSPACE_API_KEY_DENIED}`,
-      errors: RESOURCE_CONFLICT_BODY_ERRORS,
+      errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The updated skill.' },
     }),
     {
@@ -654,7 +653,7 @@ const routes = [
       summary: 'Create Custom Tool',
       description:
         'Create a code-backed custom tool in a workspace. Its title must be unique because tools resolve by title at call time.',
-      errors: RESOURCE_CONFLICT_BODY_ERRORS,
+      errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The custom tool was created.' },
     }),
     {
@@ -720,7 +719,7 @@ const routes = [
       summary: 'Update Custom Tool',
       description:
         'Update the supplied custom tool fields. Omitted fields retain their stored values, and titles must remain unique within the workspace.',
-      errors: RESOURCE_CONFLICT_BODY_ERRORS,
+      errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The updated custom tool.' },
     }),
     {
@@ -836,7 +835,7 @@ const routes = [
       operationId: 'setSecret',
       summary: 'Set Secret',
       description: `Create or replace a workspace or caller-owned personal secret. The value is encrypted at rest, is write-only, and is never included in the response. ${WORKSPACE_API_KEY_DENIED}`,
-      errors: RESOURCE_BODY_ERRORS,
+      errors: RESOURCE_ERRORS,
       success: {
         byStatus: {
           200: { description: 'The existing secret value was replaced.' },
@@ -915,6 +914,8 @@ const routes = [
   ),
 ] as const
 
+const routes = declaredRoutes.map(withRequestBodyErrors)
+
 export const resourcesOpenApiDocument = defineOpenApiDocument({
   output: 'apps/docs/openapi-v2-resources.json',
   info: {

apps/sim/lib/api/contracts/v2/openapi/shared.ts

@@ -3,6 +3,7 @@ import { v2ErrorResponseSchema } from '@/lib/api/contracts/v2/shared'
 import type {
   OpenApiErrorResponse,
   OpenApiHeader,
+  OpenApiRouteDefinition,
   OpenApiSecurityScheme,
 } from '@/lib/api/openapi/types'
 
@@ -153,33 +154,25 @@ export const RESOURCE_MUTATION_ERRORS = [
 ] as const satisfies readonly ErrorResponseId[]
 
 /**
- * The two sets below add the `413` that every body-carrying operation can emit.
+ * Adds the `413` a body-carrying operation can emit.
  *
- * It is not a property of the resource but of the request: `parseRequest` reads
- * the JSON body through `parseJsonBody` under `DEFAULT_MAX_JSON_BODY_BYTES`
- * before schema validation runs, and the v2 builders supply
- * `V2_PARSE_DEFAULTS.payloadTooLargeResponse`, so a body over
- * the cap is answered `413` on any route whose contract declares one. That made
- * `413` reachable-but-unpublished across a whole family, which is the mirror of
- * the defect these sets exist to prevent — a caller cannot handle a status the
- * spec never mentions.
+ * `parseRequest` reads the JSON body under `DEFAULT_MAX_JSON_BODY_BYTES` before
+ * schema validation, and the v2 builders supply
+ * `V2_PARSE_DEFAULTS.payloadTooLargeResponse`, so an oversized body is a real
+ * `413` on any route whose contract declares one — and a status a caller can
+ * receive but the spec omits is an unhandled branch in every generated client.
  *
- * Reachability is not automatic, so these are opt-in rather than folded into the
- * base sets. An operation with no request body cannot emit this `413` at all,
- * and neither can one whose handler reads its payload through a path that
- * applies no cap; documenting it there would publish a response that can never
- * arrive.
+ * Derived from the contract rather than chosen per operation, so a new body
+ * route cannot forget it. One-directional: it never removes a `413` from a
+ * bodyless read, several of which publish one for the folder-tree ceiling.
  */
-export const RESOURCE_BODY_ERRORS = [
-  ...RESOURCE_ERRORS,
-  'PayloadTooLarge',
-] as const satisfies readonly ErrorResponseId[]
-
-/** {@link RESOURCE_CONFLICT_ERRORS} plus the body-size `413`. */
-export const RESOURCE_CONFLICT_BODY_ERRORS = [
-  ...RESOURCE_CONFLICT_ERRORS,
-  'PayloadTooLarge',
-] as const satisfies readonly ErrorResponseId[]
+export function withRequestBodyErrors(route: OpenApiRouteDefinition): OpenApiRouteDefinition {
+  if (!route.contract.body || route.operation.errors.includes('PayloadTooLarge')) return route
+  return {
+    ...route,
+    operation: { ...route.operation, errors: [...route.operation.errors, 'PayloadTooLarge'] },
+  }
+}
 
 export const V2_API_KEY_SECURITY = [{ apiKey: [] }] as const
 

apps/sim/lib/api/contracts/v2/openapi/tables.ts

@@ -13,6 +13,7 @@ import {
   V2_COMMON_HEADERS,
   V2_ERROR_SCHEMA,
   WORKSPACE_ERRORS,
+  withRequestBodyErrors,
 } from '@/lib/api/contracts/v2/openapi/shared'
 import {
   v2AddTableColumnContract,
@@ -64,7 +65,6 @@ import {
   defineOpenApiDocument,
   defineOpenApiRoute,
   type OpenApiOperationMetadata,
-  type OpenApiRouteDefinition,
   type OpenApiSuccessMetadata,
 } from '@/lib/api/openapi/types'
 
@@ -1580,28 +1580,6 @@ const declaredRoutes = [
   ),
 ] as const
 
-/**
- * Publishes `413` on every operation that accepts a request body.
- *
- * The v2 JSON builder reads the body through `parseJsonBody` under
- * `DEFAULT_MAX_JSON_BODY_BYTES` (50 MB) BEFORE schema validation, rendering
- * `V2_PARSE_DEFAULTS.payloadTooLargeResponse`. That makes the status reachable
- * on every body-carrying operation, not just the two that set a tighter
- * `maxBodyBytes` of their own — and a status a caller can receive but the spec
- * does not declare is an unhandled branch in every generated client.
- *
- * Deliberately one-directional: it adds `413` where a body exists and never
- * removes it where none does, because several bodyless reads publish `413` for
- * the folder-tree materialization ceiling instead.
- */
-function withRequestBodyErrors(route: OpenApiRouteDefinition): OpenApiRouteDefinition {
-  if (!route.contract.body || route.operation.errors.includes('PayloadTooLarge')) return route
-  return {
-    ...route,
-    operation: { ...route.operation, errors: [...route.operation.errors, 'PayloadTooLarge'] },
-  }
-}
-
 const routes = declaredRoutes.map(withRequestBodyErrors)
 
 export const tablesOpenApiDocument = defineOpenApiDocument({