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

[waleedlatif1]

Summary

• Collapse the two internal error envelopes into one. internalOrchestrationErrorPolicy emitted { success: false, error } and internalPlainOrchestrationErrorPolicy emitted { error }; both now emit { error } under the single internalOrchestrationErrorPolicy name.
• The 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 variants disagreed on the same status across families.
• Kept the bare shape because 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.
• 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.
• Applied at the createJsonErrorResponse chokepoint plus both wrapper overrides, in the JSON and binary builders. Omitted when there is no active request scope, so unit tests are unaffected unless they opt in.
• Dropped the now-redundant internalFileErrorPolicies.plain alias.

success: true on success bodies is a separate contract and is untouched — /files/[fileId]/dimensions still returns a { success: false } domain result at 200.

Internal routes only. No /api/v1/** route changes shape.

Type of Change

• Bug fix

Testing

bun run type-check clean. 3118 API tests pass (app/api + lib/api). bun run check:api-validation passes.

Added lib/api/server/routes/request-id.test.ts and a builder test pinning the bare envelope. Verified both go red when the injection is reverted.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Aug 12, 2026 2:22am

[cursor]

PR Summary

Medium Risk
Cross-cutting change to the internal error response contract across many authenticated routes. Typed clients ignore success: false, but any ad-hoc consumers of that field could break; requestId injection is additive and scoped to internal builders.

Overview
Unifies internal API error responses onto a single bare envelope: { error, requestId? }.

Removes internalPlainOrchestrationErrorPolicy and makes internalOrchestrationErrorPolicy the only policy, dropping success: false from error bodies. Call sites across tables, workflows, knowledge, and workspace files are updated to the shared policy.

Restores requestId on internal error bodies via new withRequestId / responseWithRequestId helpers at the JSON and binary builder chokepoints (auth, parse, and projected errors). The field is omitted when there is no active request scope, so unit tests stay unchanged unless they opt in. v1/v2 public envelopes are untouched.

^{Reviewed by Cursor Bugbot for commit 8423bdc. Configure here.}

[greptile-apps]

Greptile Summary

The PR unifies internal orchestration failures under the bare error envelope and restores request IDs across generated internal errors.

• Replaces the split internal orchestration policies with one shared policy.
• Adds request-ID stamping for authentication, parsing, projected, and wrapper-generated errors in JSON and binary builders.
• Updates internal route policies and tests to reflect the unified envelope.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the previously reported authentication and parsing paths now add the active request ID to internal JSON error bodies in both builders.

Important Files Changed

Filename	Overview
apps/sim/lib/api/server/routes/internal-json-route.ts	Unifies the internal JSON error envelope and routes authentication, parsing, projected, and wrapper failures through request-ID-aware responses.
apps/sim/lib/api/server/routes/internal-binary-route.ts	Applies the same request-ID restoration to JSON error responses emitted by internal binary routes.
apps/sim/lib/api/server/routes/request-id.ts	Adds helpers to stamp object error bodies and safely rebuild existing JSON validation responses while preserving status and headers.
apps/sim/lib/api/server/routes/internal-json-route.test.ts	Covers the unified bare envelope and request IDs on authentication, parsing, and projected errors.
apps/sim/lib/api/server/routes/request-id.test.ts	Verifies request-ID injection, pass-through behavior, and preservation of response metadata.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
Request[Internal API request] --> Wrapper[withRouteHandler request scope]
Wrapper --> Auth[Authentication]
Auth -->|401| Stamp[Add requestId to JSON error]
Auth --> Parse[Contract parsing]
Parse -->|400| Rebuild[Rebuild JSON response with requestId]
Parse --> UseCase[Application use case]
UseCase -->|Projected error| Stamp
UseCase -->|Unhandled error| Callback[Wrapper error callback]
Callback --> Stamp
Stamp --> Response[Error body plus x-request-id header]
Rebuild --> Response

Loading

_{Reviews (2): Last reviewed commit: "fix(api): stamp requestId on internal au..." | Re-trigger Greptile}

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 8423bdc. Configure here.}