fix(api): give every v1 endpoint quota headers and errors that name the field (#6012)

* fix(api): give every v1 endpoint quota headers and errors that name the field

Three consistency gaps found by probing the live v1 surface end to end.

Rate-limit headers were only published by routes built on createApiResponse —
workflows, logs and audit-logs. Tables, files and knowledge are rate limited by
the same bucket and will return 429, but published no quota on success, so a
client discovered the ceiling only by hitting it. Adds a shared
rateLimitHeaders() builder, reused by createRateLimitResponse, and attaches it
to all 31 success responses on those three families.

Missing required fields did not name themselves. .min(1, '...') only fires for
a present-but-empty string, so an omitted field fell through to Zod's default
"Invalid input: expected string, received undefined". A previous pass fixed the
shared id schemas, but 22 of 23 v1 workspaceId declarations bypassed them, so
the fix reached almost nothing. Adds requiredFieldSchema(message) and routes
every v1 request input through it, preserving each site's existing, more
specific wording (for example "workspaceId query parameter is required")
instead of flattening them to the generic one. Response schemas are left alone
— "required" wording would be wrong there.

Validation failures on tables, files and knowledge reported the literal
"Validation error" and discarded the schema's message. Adds
v1ValidationErrorResponse, which surfaces the first issue while keeping
details, and wires it into the 19 parseRequest calls that had no handler.
Routes with deliberately specific wording keep theirs. The global default is
untouched, since routes outside v1 assert the current string.

* fix(api): finish the v1 consistency sweep at call level, not file level

Review found three places the first pass missed, all from filters that worked
on whole files instead of individual call sites.

- GET /api/v1/files/{fileId} returns the file bytes via `new Response`, not a
  `success: true` JSON body, so the header pass skipped it. The download now
  carries the same quota headers as the DELETE beside it.
- Four parseRequest calls in the table-row routes still reported the generic
  "Validation error". The first pass skipped any file that already had a
  handler anywhere in it, which excluded these two files wholesale. The check
  is now per call site, and no bare call remains.
- POST /api/v1/tables takes its body from the shared tables contract, which
  still used the bare `.min(1)` form, so an omitted workspaceId did not name
  itself. Converted there and in the other v1-reachable contracts.

Scope note: roughly a thousand `.min(1, '... is required')` declarations remain
under contracts/tools/**. Those are block and tool definitions rather than the
public REST surface, and converting them belongs in its own change.

* refactor(api): publish quota headers from one chokepoint, not 32 call sites

A quality pass found the previous commit only made the happy path consistent.
Those three route families have 117 response sites; 32 got headers. The other
85 are the error paths — 400/403/404/500 — which are exactly the responses a
client is deciding whether to retry, and they published no quota at all.

`checkRateLimit` now records the bucket snapshot against the request, and
`withRouteHandler` attaches the headers next to the `x-request-id` it already
sets, on both the success and the unhandled-error branch. Every v1 response
carries the quota now, and a new v1 route gets it without remembering to. The
carrier is a WeakMap keyed by the request, so it needs no cleanup and routes
that never record a snapshot — everything outside v1 — are untouched.

This deletes more than it adds: the 32 decorations are gone, and so is the
`rateLimit` parameter that had been threaded into `handleBatchInsert` purely so
a business-logic helper could decorate its own response.

Also from the same pass:
- One definition of the header trio. `createApiResponse` had its own copy, so
  after the last commit there were two; both now build from
  `buildRateLimitHeaders`.
- `v1ValidationErrorResponse` delegates to the shared `validationErrorResponse`
  instead of hand-rolling the same body, and takes a fallback message, which
  collapses four route closures that differed only in that string.
- 36 sites wrote `requiredFieldSchema('Workspace ID is required')` — the
  verbatim definition of the exported `workspaceIdSchema`. Using the primitive
  is the whole point of having it; they now import it.
- Dropped TSDoc that had gone stale or contradicted the call sites it advised.

* docs(api): reattach the withRouteHandler docblock and drop stale wording

The comment pass caught a real casualty of the previous commit: inserting
`applyResponseHeaders` put it between `withRouteHandler`'s docblock and the
function itself, so the file's most-used export lost its documentation to the
new private helper. Reattached, and its header bullet now mentions the
rate-limit trio it also emits.

Remaining edits are wording only. The WeakMap rationale moved off
`RateLimitSnapshot` — three self-evident fields — onto the `snapshots`
declaration it actually describes. The record site no longer restates that
rationale; it keeps only the part unique to it. And three id-schema docs claimed
"same constraint as nonEmptyIdSchema", which stopped being true when that
schema was documented as deliberately message-less.

* docs(api): document the quota headers on every v1 success response

The spec already asserted, in the RateLimited description, that the
X-RateLimit-* trio accompanies every authenticated response. Before this branch
that was false for tables, files and knowledge; it is true now, but no operation
documented it — only 1 of 40 v1 success responses carried the headers.

All 40 now reference the shared header components. The shared BadRequest,
Forbidden and NotFound components are deliberately left alone: they are also
$ref-ed by non-v1 operations that publish no quota, so annotating them there
would over-claim. The RateLimited description carries the general rule instead,
now stating explicitly that the only responses without the headers are the ones
that failed authentication.

* fix(api): stop the last v1 validation paths from swallowing the message

Bugbot found GET /api/v1/tables/{tableId}/rows still answering with the bare
"Validation error". Its handler special-cases malformed filter/sort JSON and
then falls back to the shared helper — so the site looked handled to a check
that only asked whether a handler existed, which is why the earlier call-level
sweep passed over it.

Auditing the whole class turned up more of the same shape:
- The optional-body parses on deploy and rollback, where a bad `version` lost
  "version must be a positive integer".
- Eleven catch-block `validationErrorResponseFromError` handlers across the
  table routes, which discard the message of any ZodError thrown deeper.

Adds `v1ValidationErrorResponseFromError` as the v1 counterpart for unknown
caught values, and routes every remaining v1 validation path through the v1
helpers. No call to the generic helpers survives under app/api/v1 outside
admin, which keeps its own error envelope.

Author: waleedlatif1

apps/docs/openapi.json

@@ -26,6 +26,8 @@ const {
 vi.mock('@/app/api/v1/middleware', () => ({
   checkRateLimit: mockCheckRateLimit,
   createRateLimitResponse: vi.fn(),
+  v1ValidationErrorResponse: (e: { issues: unknown[] }) =>
+    NextResponse.json({ error: 'Validation error', details: e.issues }, { status: 400 }),
 }))
 
 vi.mock('@/app/api/v1/audit-logs/auth', () => ({

apps/sim/app/api/v1/audit-logs/route.test.ts

@@ -24,7 +24,7 @@ import { getErrorMessage } from '@sim/utils/errors'
 import { generateId } from '@sim/utils/id'
 import { type NextRequest, NextResponse } from 'next/server'
 import { v1ListAuditLogsContract } from '@/lib/api/contracts/v1/audit-logs'
-import { getValidationErrorMessage, parseRequest } from '@/lib/api/server'
+import { parseRequest } from '@/lib/api/server'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { validateEnterpriseAuditAccess } from '@/app/api/v1/audit-logs/auth'
 import { formatAuditLogEntry } from '@/app/api/v1/audit-logs/format'
@@ -35,7 +35,11 @@ import {
   queryAuditLogs,
 } from '@/app/api/v1/audit-logs/query'
 import { createApiResponse, getUserLimits } from '@/app/api/v1/logs/meta'
-import { checkRateLimit, createRateLimitResponse } from '@/app/api/v1/middleware'
+import {
+  checkRateLimit,
+  createRateLimitResponse,
+  v1ValidationErrorResponse,
+} from '@/app/api/v1/middleware'
 
 const logger = createLogger('V1AuditLogsAPI')
 
@@ -65,14 +69,7 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
       request,
       {},
       {
-        validationErrorResponse: (error) =>
-          NextResponse.json(
-            {
-              error: getValidationErrorMessage(error, 'Invalid parameters'),
-              details: error.issues,
-            },
-            { status: 400 }
-          ),
+        validationErrorResponse: (error) => v1ValidationErrorResponse(error, 'Invalid parameters'),
       }
     )
     if (!parsed.success) return parsed.response

apps/sim/app/api/v1/audit-logs/route.ts

@@ -20,6 +20,8 @@ vi.mock('@/app/api/v1/middleware', () => ({
   checkRateLimit: mockCheckRateLimit,
   createRateLimitResponse: () => new Response('rate limited', { status: 429 }),
   validateWorkspaceAccess: mockValidateWorkspaceAccess,
+  v1ValidationErrorResponse: (e: { issues: unknown[] }) =>
+    NextResponse.json({ error: 'Validation error', details: e.issues }, { status: 400 }),
 }))
 vi.mock('@/lib/uploads/contexts/workspace', () => ({
   getWorkspaceFile: mockGetWorkspaceFile,

apps/sim/app/api/v1/files/[fileId]/route.test.ts

@@ -15,6 +15,7 @@ import { performDeleteWorkspaceFileItems } from '@/lib/workspace-files/orchestra
 import {
   checkRateLimit,
   createRateLimitResponse,
+  v1ValidationErrorResponse,
   validateWorkspaceAccess,
 } from '@/app/api/v1/middleware'
 
@@ -38,7 +39,9 @@ export const GET = withRouteHandler(async (request: NextRequest, context: FileRo
     }
 
     const userId = rateLimit.userId!
-    const parsed = await parseRequest(v1DownloadFileContract, request, context)
+    const parsed = await parseRequest(v1DownloadFileContract, request, context, {
+      validationErrorResponse: v1ValidationErrorResponse,
+    })
     if (!parsed.success) return parsed.response
 
     const { fileId } = parsed.data.params
@@ -119,7 +122,9 @@ export const DELETE = withRouteHandler(async (request: NextRequest, context: Fil
     }
 
     const userId = rateLimit.userId!
-    const parsed = await parseRequest(v1DeleteFileContract, request, context)
+    const parsed = await parseRequest(v1DeleteFileContract, request, context, {
+      validationErrorResponse: v1ValidationErrorResponse,
+    })
     if (!parsed.success) return parsed.response
 
     const { fileId } = parsed.data.params

apps/sim/app/api/v1/files/[fileId]/route.ts

@@ -22,6 +22,7 @@ import {
   checkRateLimit,
   checkWorkspaceScope,
   createRateLimitResponse,
+  v1ValidationErrorResponse,
   validateWorkspaceAccess,
 } from '@/app/api/v1/middleware'
 
@@ -43,7 +44,14 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
     }
 
     const userId = rateLimit.userId!
-    const parsed = await parseRequest(v1ListFilesContract, request, {})
+    const parsed = await parseRequest(
+      v1ListFilesContract,
+      request,
+      {},
+      {
+        validationErrorResponse: v1ValidationErrorResponse,
+      }
+    )
     if (!parsed.success) return parsed.response
 
     const { workspaceId } = parsed.data.query

apps/sim/app/api/v1/files/route.ts

@@ -11,7 +11,7 @@ import { parseRequest } from '@/lib/api/server'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { deleteDocument } from '@/lib/knowledge/documents/service'
 import { handleError, resolveKnowledgeBase, serializeDate } from '@/app/api/v1/knowledge/utils'
-import { authenticateRequest } from '@/app/api/v1/middleware'
+import { authenticateRequest, v1ValidationErrorResponse } from '@/app/api/v1/middleware'
 
 export const dynamic = 'force-dynamic'
 export const revalidate = 0
@@ -28,7 +28,9 @@ export const GET = withRouteHandler(
     const { requestId, userId, rateLimit } = auth
 
     try {
-      const parsed = await parseRequest(v1GetKnowledgeDocumentContract, request, context)
+      const parsed = await parseRequest(v1GetKnowledgeDocumentContract, request, context, {
+        validationErrorResponse: v1ValidationErrorResponse,
+      })
       if (!parsed.success) return parsed.response
       const { id: knowledgeBaseId, documentId } = parsed.data.params
 
@@ -117,7 +119,9 @@ export const DELETE = withRouteHandler(
     const { requestId, userId, rateLimit } = auth
 
     try {
-      const parsed = await parseRequest(v1DeleteKnowledgeDocumentContract, request, context)
+      const parsed = await parseRequest(v1DeleteKnowledgeDocumentContract, request, context, {
+        validationErrorResponse: v1ValidationErrorResponse,
+      })
       if (!parsed.success) return parsed.response
       const { id: knowledgeBaseId, documentId } = parsed.data.params
 

apps/sim/app/api/v1/knowledge/[id]/documents/[documentId]/route.ts

@@ -46,6 +46,8 @@ const SYSTEM_BILLING_ATTRIBUTION = {
 
 vi.mock('@/app/api/v1/middleware', () => ({
   authenticateRequest: mockAuthenticateRequest,
+  v1ValidationErrorResponse: (e: { issues: unknown[] }) =>
+    NextResponse.json({ error: 'Validation error', details: e.issues }, { status: 400 }),
 }))
 
 vi.mock('@/app/api/v1/knowledge/utils', () => ({

apps/sim/app/api/v1/knowledge/[id]/documents/route.test.ts

@@ -26,7 +26,7 @@ import type { DocumentSortField, SortOrder } from '@/lib/knowledge/documents/typ
 import { uploadWorkspaceFile } from '@/lib/uploads/contexts/workspace'
 import { validateFileType } from '@/lib/uploads/utils/validation'
 import { handleError, resolveKnowledgeBase, serializeDate } from '@/app/api/v1/knowledge/utils'
-import { authenticateRequest } from '@/app/api/v1/middleware'
+import { authenticateRequest, v1ValidationErrorResponse } from '@/app/api/v1/middleware'
 
 export const dynamic = 'force-dynamic'
 export const revalidate = 0
@@ -44,7 +44,9 @@ export const GET = withRouteHandler(async (request: NextRequest, context: Docume
   const { requestId, userId, rateLimit } = auth
 
   try {
-    const parsed = await parseRequest(v1ListKnowledgeDocumentsContract, request, context)
+    const parsed = await parseRequest(v1ListKnowledgeDocumentsContract, request, context, {
+      validationErrorResponse: v1ValidationErrorResponse,
+    })
     if (!parsed.success) return parsed.response
 
     const { workspaceId, limit, offset, search, enabledFilter, sortBy, sortOrder } =
@@ -99,7 +101,9 @@ export const POST = withRouteHandler(
     const { requestId, userId, rateLimit } = auth
 
     try {
-      const parsed = await parseRequest(v1UploadKnowledgeDocumentContract, request, context)
+      const parsed = await parseRequest(v1UploadKnowledgeDocumentContract, request, context, {
+        validationErrorResponse: v1ValidationErrorResponse,
+      })
       if (!parsed.success) return parsed.response
       const { id: knowledgeBaseId } = parsed.data.params
 

apps/sim/app/api/v1/knowledge/[id]/documents/route.ts

@@ -13,7 +13,7 @@ import {
   handleError,
   resolveKnowledgeBase,
 } from '@/app/api/v1/knowledge/utils'
-import { authenticateRequest } from '@/app/api/v1/middleware'
+import { authenticateRequest, v1ValidationErrorResponse } from '@/app/api/v1/middleware'
 
 export const dynamic = 'force-dynamic'
 export const revalidate = 0
@@ -29,7 +29,9 @@ export const GET = withRouteHandler(async (request: NextRequest, context: Knowle
   const { requestId, userId, rateLimit } = auth
 
   try {
-    const parsed = await parseRequest(v1GetKnowledgeBaseContract, request, context)
+    const parsed = await parseRequest(v1GetKnowledgeBaseContract, request, context, {
+      validationErrorResponse: v1ValidationErrorResponse,
+    })
     if (!parsed.success) return parsed.response
 
     const { id } = parsed.data.params
@@ -54,7 +56,9 @@ export const PUT = withRouteHandler(async (request: NextRequest, context: Knowle
   const { requestId, userId, rateLimit } = auth
 
   try {
-    const parsed = await parseRequest(v1UpdateKnowledgeBaseContract, request, context)
+    const parsed = await parseRequest(v1UpdateKnowledgeBaseContract, request, context, {
+      validationErrorResponse: v1ValidationErrorResponse,
+    })
     if (!parsed.success) return parsed.response
 
     const { id } = parsed.data.params
@@ -106,7 +110,9 @@ export const DELETE = withRouteHandler(
     const { requestId, userId, rateLimit } = auth
 
     try {
-      const parsed = await parseRequest(v1DeleteKnowledgeBaseContract, request, context)
+      const parsed = await parseRequest(v1DeleteKnowledgeBaseContract, request, context, {
+        validationErrorResponse: v1ValidationErrorResponse,
+      })
       if (!parsed.success) return parsed.response
 
       const { id } = parsed.data.params