feat(api): document declared error shapes across public oRPC routes (#1109)

* feat(api): document declared error shapes across public oRPC routes

Attach commonApiErrors (401/403/422/429/500 + workspace-access denials)
once to the shared public API stacks in orpc.ts, so every public
procedure inherits a consistent OpenAPI error contract without a
per-router .errors() call. Remap oRPC's own BAD_REQUEST validation
throw to 422 so schema-level and business-level validation failures
share one status, and align validationException to 422 to match.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VWhmQGALFoH4NVXMsXypA

* chore: fix revie

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: realcodesiman

.agents/skills/orpc-api/SKILL.md

@@ -168,6 +168,7 @@ generated `operationId` (`myFeature.get`), which the MCP server turns into
 the tool name (`my_feature_get`).
 
 ```typescript
+import { possibleErrorsOnFindingResource } from "@/lib/orpc/orpc-error-helper"
 import { workspaceTokenAuthAPIForScope } from "@/orpc"
 
 // Pick the resource-area scope this feature belongs to
@@ -184,6 +185,8 @@ export const myFeaturePublicRouter = {
     })
     .input(z.object({ id: zodBigintAsString() }))
     .output(publicMyFeatureResponse)
+    // Declares only what varies by operation shape — see "Declared errors"
+    .errors(possibleErrorsOnFindingResource)
     .handler(async ({ context, input }) => {
       // context.workspace is available from token auth
       return await findMyFeature({
@@ -385,6 +388,41 @@ throw notFoundException("Item not found")
 throw new ChatbotXException("Custom error", "BAD_REQUEST", 400)
 ```
 
+### Declared errors (`.errors()`) — public routes only
+
+Every public procedure must declare the errors it can throw, because that
+declaration is what renders the non-2xx responses in the OpenAPI spec (and
+what the MCP server and CLI show a caller). The declaration is split in two:
+
+| Layer | Where | Contains |
+|-------|-------|----------|
+| Shared | `commonApiErrors`, attached **once** to the public stacks in `@/orpc` | 401 (`UNAUTHORIZED`, `INVALID_CHATBOT_TOKEN`), 403 (`FORBIDDEN`, `trialExpired`, `macLimitReached`), 422 (`invalidRequestData`, `validation`), 429 (`tooManyRequests`), 500 (`INTERNAL_SERVER_ERROR`) |
+| Per-route | one `possibleErrorsOn*Resource` set from `@/lib/orpc/orpc-error-helper` | only what varies by operation shape — `notFound` (404) and `businessError` (400) |
+
+Pick the per-route set by what the handler can actually fail with, not by the
+HTTP verb:
+
+- `possibleErrorsOnListingResource` — a collection read that cannot 404.
+- `possibleErrorsOnFindingResource` — a read that resolves one resource.
+- `possibleErrorsOnCreatingResource` — a create with no parent lookup.
+- `possibleErrorsOnMutatingResource` — an update, **or a create that resolves a
+  parent from a path param** (e.g. `POST /v1/contacts/{identifier}/notes` calls
+  `contactService.resolveIdByIdentifier`, which throws 404).
+- `possibleErrorsOnDeletingResource` — a delete.
+
+**Never re-declare a `commonApiErrors` code in a per-route set.** Doing so
+duplicates the entry in the generated spec. The guard in
+`apps/builder/__tests__/public-spec-operations.test.ts` fails on both mistakes:
+a route missing a universal code, and a duplicated one.
+
+**The `code` string is the contract, not the status.** oRPC matches a thrown
+`ORPCError` to its declaration by `code` *and* exact `status`
+(`validateORPCError` in `@orpc/contract`). On a miss it does not error — it
+returns the error with `defined: false`, so an undeclared code still reaches
+the client but never appears in the spec. That silent degrade is why a new
+`ChatbotXException` code thrown from a public route needs a matching entry in
+one of these sets.
+
 ## Logging
 
 Import the logger from the nearest `lib/log` or `lib/logger` module. Never use `console` in handlers.

apps/builder/__tests__/orpc-error-mapping.test.ts

@@ -49,6 +49,18 @@ vi.mock("@chatbotx.io/sdk", () => ({
   },
 }))
 
+// `@/orpc` now attaches `commonApiErrors` (from orpc-error-helper.ts) to the
+// public stacks, which reuses `DENIAL_MESSAGES` from this module — stub it so
+// importing `@/orpc` doesn't pull in the real `@chatbotx.io/business` barrel
+// (and transitively the google-calendar integration's `@chatbotx.io/sdk`
+// `Integration` export, which the mock above doesn't provide).
+vi.mock("@/lib/workspace/authorize-workspace-access", () => ({
+  DENIAL_MESSAGES: {
+    trialExpired: "Trial expired",
+    macLimitReached: "Monthly active contact limit reached",
+  },
+}))
+
 const { ChatbotXException } = await import("@chatbotx.io/business/errors")
 const { ModelNotfoundException } = await import("@chatbotx.io/database/errors")
 const { SdkException } = await import("@chatbotx.io/sdk")
@@ -106,6 +118,28 @@ describe("mapKnownOrpcErrors", () => {
     expect(mockLoggerWarn).toHaveBeenCalledTimes(1)
   })
 
+  test("maps a validationException-shaped ChatbotXException to a 422 validation error", () => {
+    const error = new ChatbotXException("Name already taken", "validation", 422)
+
+    expect(() => mapKnownOrpcErrors(error)).toThrow(
+      expect.objectContaining({ code: "validation", status: 422 }),
+    )
+    expect(mockLoggerWarn).toHaveBeenCalledTimes(1)
+  })
+
+  test("maps a tooManyRequests ChatbotXException to a 429 error", () => {
+    const error = new ChatbotXException(
+      "Too many requests. Retry after 5s.",
+      "tooManyRequests",
+      429,
+    )
+
+    expect(() => mapKnownOrpcErrors(error)).toThrow(
+      expect.objectContaining({ code: "tooManyRequests", status: 429 }),
+    )
+    expect(mockLoggerWarn).toHaveBeenCalledTimes(1)
+  })
+
   test("maps a 5xx ChatbotXException without warn-logging — the route callback logs it once", () => {
     const error = new ChatbotXException("boom", "upstream", 502)
 

apps/builder/__tests__/public-spec-operations.test.ts

@@ -30,6 +30,7 @@ type SpecOperation = {
   tags: string[]
   summary?: string
   security?: Record<string, string[]>[]
+  responseStatuses: string[]
 }
 
 const LEGACY_WORKSPACE_TOKEN_PATTERN = /workspace[_.]?token/i
@@ -133,6 +134,7 @@ beforeAll(async () => {
         tags: op.tags ?? [],
         summary: op.summary,
         security: op.security,
+        responseStatuses: Object.keys(op.responses ?? {}),
       })
 
       const successResponse = Object.entries(op.responses ?? {}).find(
@@ -221,3 +223,68 @@ describe("public API spec — operation naming guard", () => {
     }
   })
 })
+
+const PATH_PARAM_PATTERN = /\{[^}]+\}/
+
+describe("public API spec — error response coverage", () => {
+  const COMMON_ERROR_STATUSES = ["400", "401", "403", "429", "500"]
+
+  // `channels.me` has no `.input()` and no possible business-logic failure —
+  // it echoes the authenticated token's identity — so it legitimately has no
+  // 400 (business error) or 422 (validation error) case.
+  const NO_400_OPERATION_IDS = new Set(["channels.me"])
+
+  test("every operation documents the shared 400/401/403/429/500 errors", () => {
+    const missing = operations
+      .filter((op) => !NO_400_OPERATION_IDS.has(op.operationId))
+      .filter((op) =>
+        COMMON_ERROR_STATUSES.some(
+          (status) => !op.responseStatuses.includes(status),
+        ),
+      )
+      .map((op) => op.operationId)
+
+    expect(missing).toEqual([])
+  })
+
+  test("every DELETE, PUT/PATCH, and GET-by-id operation documents 404", () => {
+    const shouldDocument404 = operations.filter(
+      (op) =>
+        op.method === "DELETE" ||
+        op.method === "PUT" ||
+        op.method === "PATCH" ||
+        (op.method === "GET" && PATH_PARAM_PATTERN.test(op.path)),
+    )
+
+    expect(shouldDocument404.length).toBeGreaterThan(0)
+
+    const missing404 = shouldDocument404
+      .filter((op) => !op.responseStatuses.includes("404"))
+      .map((op) => op.operationId)
+
+    expect(missing404).toEqual([])
+  })
+
+  test("every POST/PUT/PATCH operation documents 422", () => {
+    const bodyMethods = operations.filter(
+      (op) =>
+        op.method === "POST" || op.method === "PUT" || op.method === "PATCH",
+    )
+
+    expect(bodyMethods.length).toBeGreaterThan(0)
+
+    const missing422 = bodyMethods
+      .filter((op) => !op.responseStatuses.includes("422"))
+      .map((op) => op.operationId)
+
+    expect(missing422).toEqual([])
+  })
+
+  test("no operation documents 413 — the payload-too-large status is out of scope", () => {
+    const with413 = operations
+      .filter((op) => op.responseStatuses.includes("413"))
+      .map((op) => op.operationId)
+
+    expect(with413).toEqual([])
+  })
+})

apps/builder/__tests__/workspace-token-auth-middleware.test.ts

@@ -118,6 +118,7 @@ describe("workspaceTokenAuthMidddleware", () => {
 
     await expect(callMiddleware(headers, "GET")).rejects.toMatchObject({
       code: "INVALID_CHATBOT_TOKEN",
+      status: 401,
     })
   })
 
@@ -128,6 +129,7 @@ describe("workspaceTokenAuthMidddleware", () => {
 
     await expect(callMiddleware(headers, "GET")).rejects.toMatchObject({
       code: "INVALID_CHATBOT_TOKEN",
+      status: 401,
     })
     expect(findWorkspaceByTokenHash).toHaveBeenCalledTimes(1)
     // Invalid guesses never resolve a workspace, so only the pre-auth

apps/builder/__tests__/workspace-token-scope-enforcement.test.ts

@@ -182,6 +182,19 @@ describe("workspace API token resource-scope enforcement", () => {
 
     await expect(invoke(procedure)).rejects.toMatchObject({
       code: "INVALID_CHATBOT_TOKEN",
+      status: 401,
+    })
+  })
+
+  test("an invalid token error is upgraded to defined:true once commonApiErrors is attached", async () => {
+    findWorkspaceByTokenHash.mockResolvedValue(undefined)
+
+    const procedure = buildProcedure("contacts", "GET")
+
+    await expect(invoke(procedure)).rejects.toMatchObject({
+      code: "INVALID_CHATBOT_TOKEN",
+      status: 401,
+      defined: true,
     })
   })
 })

apps/builder/src/enterprise/features/inbox-teams/api/public.ts

@@ -1,3 +1,4 @@
+import { possibleErrorsOnListingResource } from "@/lib/orpc/orpc-error-helper"
 import { paginateInMemory, publicListRequest } from "@/lib/public-api/list"
 import { workspaceTokenAuthAPIForScope } from "@/orpc"
 import { listInboxTeams } from "../queries"
@@ -15,6 +16,7 @@ export const inboxTeamsPublicRouter = {
     })
     .input(publicListRequest)
     .output(publicListInboxTeamsResponse)
+    .errors(possibleErrorsOnListingResource)
     .handler(async ({ context, input }) => {
       const { data } = await listInboxTeams({
         workspaceId: context.workspace.id,

apps/builder/src/features/ai-agents/api/public.ts

@@ -1,4 +1,5 @@
 import { aiAgentService } from "@chatbotx.io/business"
+import { possibleErrorsOnListingResource } from "@/lib/orpc/orpc-error-helper"
 import { publicListRequest } from "@/lib/public-api/list"
 import { workspaceTokenAuthAPIForScope } from "@/orpc"
 import { listAIAgentsResponse } from "../schema/query"
@@ -15,6 +16,7 @@ export const aiAgentsPublicRouter = {
     })
     .input(publicListRequest)
     .output(listAIAgentsResponse)
+    .errors(possibleErrorsOnListingResource)
     .handler(
       async ({ context, input }) =>
         await aiAgentService.listAIAgents({

apps/builder/src/features/automated-response/api/public.ts

@@ -1,4 +1,5 @@
 import { automatedResponseService } from "@chatbotx.io/business"
+import { possibleErrorsOnListingResource } from "@/lib/orpc/orpc-error-helper"
 import { publicListRequest, publicListResponse } from "@/lib/public-api/list"
 import { workspaceTokenAuthAPIForScope } from "@/orpc"
 import { publicKeywordResource } from "../schema/resource"
@@ -15,6 +16,7 @@ export const keywordsPublicRouter = {
     })
     .input(publicListRequest)
     .output(publicListResponse(publicKeywordResource))
+    .errors(possibleErrorsOnListingResource)
     .handler(async ({ context, input }) => {
       const result = await automatedResponseService.list({
         workspaceId: context.workspace.id,

apps/builder/src/features/bot-fields/api/public.ts

@@ -4,6 +4,7 @@ import {
   possibleErrorsOnCreatingResource,
   possibleErrorsOnDeletingResource,
   possibleErrorsOnFindingResource,
+  possibleErrorsOnMutatingResource,
 } from "@/lib/orpc/orpc-error-helper"
 import { publicListRequest } from "@/lib/public-api/list"
 import { workspaceTokenAuthAPIForScope } from "@/orpc"
@@ -84,7 +85,7 @@ export const botFieldsPublicRouter = {
       z.object({ idOrName: z.string().max(255), value: z.string().max(255) }),
     )
     .output(publicBotFieldResource)
-    .errors(possibleErrorsOnCreatingResource)
+    .errors(possibleErrorsOnMutatingResource)
     .handler(async ({ context, input }) => {
       const { idOrName, ...rest } = input
       return await botFieldService.updateByKey({
@@ -109,7 +110,7 @@ export const botFieldsPublicRouter = {
         ),
       }),
     )
-    .errors(possibleErrorsOnCreatingResource)
+    .errors(possibleErrorsOnMutatingResource)
     .handler(async ({ context, input }) => {
       await Promise.all(
         input.fields.map(({ key, value }) =>
@@ -146,7 +147,7 @@ export const botFieldsPublicRouter = {
         ),
       }),
     )
-    .errors(possibleErrorsOnCreatingResource)
+    .errors(possibleErrorsOnMutatingResource)
     .handler(async ({ context, input }) => {
       await botFieldService.bulkUpdateByKeys({
         workspaceId: context.workspace.id,

apps/builder/src/features/broadcasts/api/public.ts

@@ -1,4 +1,8 @@
 import z from "zod"
+import {
+  possibleErrorsOnFindingResource,
+  possibleErrorsOnListingResource,
+} from "@/lib/orpc/orpc-error-helper"
 import { publicListRequest } from "@/lib/public-api/list"
 import { workspaceTokenAuthAPIForScope } from "@/orpc"
 import {
@@ -24,6 +28,7 @@ export const broadcastsPublicRouter = {
     })
     .input(publicListRequest)
     .output(publicListBroadcastsResponse)
+    .errors(possibleErrorsOnListingResource)
     .handler(
       async ({ context, input }) =>
         await listBroadcasts({
@@ -43,6 +48,7 @@ export const broadcastsPublicRouter = {
     })
     .input(z.object({ idOrName: z.string() }))
     .output(publicBroadcastResource)
+    .errors(possibleErrorsOnFindingResource)
     .handler(
       async ({ context, input }) =>
         await publicGetBroadcast(context.workspace.id, input.idOrName),
@@ -63,6 +69,7 @@ export const broadcastsPublicRouter = {
       }),
     )
     .output(listBroadcastAudienceResponse)
+    .errors(possibleErrorsOnFindingResource)
     .handler(async ({ context, input }) => {
       const broadcast = await publicGetBroadcast(
         context.workspace.id,