tRPC 401 vs REST: when a reviewer's suggestion is right in substance, wrong in transport

An external reviewer told me to add a tRPC aggregation endpoint to feed a dashboard zone. The design was right. The transport was wrong, and I knew it the second I read the suggestion, because I’d just spent the morning learning that this particular surface authenticates with a vault-key bearer token and tRPC’s protectedProcedure returns 401 on that path. The reviewer reasoned about the architecture perfectly. They just didn’t have my auth context, so they reached for the wire that doesn’t carry my credential.

This is a small thing to get wrong and a small thing to fix, but the pattern under it shows up every time you run a design past someone outside your codebase. So let me lay out the actual situation, then the rule.

The setup

I was rebuilding a cockpit dashboard for an internal agent system. The old version had grown to twenty equal collapsible sections and instantly buried its own best feature, so the redesign collapsed everything into three fixed unequal zones: needs-me-now, live-now, and at-a-glance. The at-a-glance zone needed one thing the old layout never had: a single aggregation endpoint that fans out a handful of queries in parallel and returns a combined snapshot.

I ran the redesign plan through two external AI reviewers in sequence, codex first and manus second. They converged on the same shape for that endpoint, which is usually a good sign:

• run the underlying queries in parallel, not sequentially
• put a strict timeout on the whole aggregation
• return partial data on timeout instead of failing the whole call

That is the correct design for a dashboard tile. You never want one slow query to stall the panel, and a dashboard would rather show four of five numbers with one marked stale than show a spinner or an error. I had no argument with any of it. Manus, reviewing second, was the one who added the partial-data-on-timeout behavior on top of codex’s parallel-query-with-a-timeout shape, which is exactly the kind of second-pass tightening you want from a reviewer who can see the first reviewer’s notes.

Then manus said: put it on tRPC.

Why tRPC was the wrong wire here

The cockpit doesn’t authenticate the way the rest of the tRPC surface does. It authenticates with a vault-key bearer token. The cockpit server runs as tsx watch on the working tree behind caddy, and the routes that this dashboard hits come in carrying that bearer, not a session that tRPC’s auth middleware recognizes.

tRPC’s protectedProcedure is the middleware that gates authenticated procedures. It checks for the auth context it expects, and when the request is carrying a vault-key bearer instead, that check fails and the procedure returns 401. Not 403, not a custom error. A flat 401 before any of your handler code runs. So if I’d taken manus’s suggestion literally and written the aggregation as a protectedProcedure, the endpoint would have been correct in every respect except that nothing could ever call it. The parallel queries, the strict timeout, the partial-data fallback, all of it sitting behind a 401 the dashboard’s bearer token can’t clear.

The fix was not to argue with the design. The design was right. The fix was to keep the entire substance and change the transport. The aggregation went on REST instead, at /api/pm/cockpit, which already lives in the request path that the vault-key bearer authenticates against, the same path the dashboard tree and the agent-system panel already load through. Same parallel queries. Same strict timeout. Same partial-data-on-timeout behavior manus added. Different wire, the one that actually carries my credential.

That is the whole gotcha. Right substance, wrong transport, and the only thing that needed to move was which protocol the logic hung off of.

Why a smart reviewer makes this exact mistake

This is not a knock on the reviewer. It’s structural. An external reviewer, human or model, reasons about your architecture from the artifacts you hand them: the design doc, the file tree, the description of what you’re building. What they almost never have is your auth context. They don’t know that one surface gets a session cookie and another gets a vault-key bearer, that one path runs through tRPC’s protectedProcedure and another runs through a REST handler that validates the bearer directly. That knowledge lives in your head and in scattered middleware, not in the design doc you sent out.

So when a reviewer sees “you need an authenticated aggregation endpoint,” they reach for whatever authenticated-endpoint pattern is most visible in your stack. If your codebase reads as a tRPC app, they’ll say tRPC, because that’s where authenticated procedures live in the part of the system they can see. They’re answering the question “what’s a good authenticated aggregation endpoint” correctly. They just can’t answer “and which transport does this specific surface’s credential clear,” because that’s the one fact you didn’t give them and probably couldn’t have, short of pasting your auth middleware.

The same day, the same two reviewers got several other things right that I shipped almost verbatim, and got one citation wrong that I had to verify against the real file before building on it. Codex pointed me at a spawn endpoint as the seam to reuse and cited a line that didn’t exist in the actual 1218-line file. The design instinct was sound, the endpoint was real and I did build on it, but the specific line was off, so I verified the seam against the source before relying on it. Same shape as the tRPC call: the thinking is good, the detail that depends on ground truth you didn’t supply is where it slips.

The rule

Keep the reviewer’s design substance. Swap the transport to match what actually authenticates.

When you cascade a plan through outside reviewers, you are the editor, not a passthrough. The value of a reviewer who can see the previous reviewer’s pass is real. Manus took codex’s parallel-query-with-a-timeout endpoint and added the partial-data-on-timeout fallback, and I shipped that. But the reviewer is an input, not an oracle, and the parts of their suggestion that depend on context they don’t have are exactly the parts you have to catch.

A short checklist I now run on any reviewer suggestion that touches a wire or an endpoint:

• Does the suggested transport sit in the request path this surface’s credential actually authenticates against? A vault-key bearer doesn’t clear protectedProcedure. A session cookie might not clear a service-to-service REST handler. Know which credential hits which gate.
• Is the thing they got right the design, or the transport? Usually it’s the design. Salvage that and re-host it.
• Did they cite a specific file, line, or symbol? Verify it against the real source before you build on it. Good reasoning attaches itself to wrong anchors constantly.

The failure mode to avoid is treating a reviewer’s suggestion as atomic, accept-the-whole-thing or reject-the-whole-thing. It almost never is. The design and the delivery are separable, and the delivery is where outside reviewers go wrong, because delivery is where your private auth context lives. Take the design. Change the wire. Move on.

The endpoint shipped on REST at /api/pm/cockpit, parallel queries with a strict timeout and partial data on timeout. Every bit of the reviewer’s substance survived. The only thing I threw away was the protocol they named, and I threw it away in the same breath I read it, because I already knew the bearer token returns 401 down the tRPC path.

Related

• Letting a Second AI Review Your Toolkit Design, and Where I Overruled It: another case where the reviewer’s direction was right but required author judgment to land correctly
• All Seven Reviewers Passed. The Writing Was Worse. Here’s What Went Wrong.: when accepting reviewer suggestions uncritically degrades the result
• A three-pass AI code review that kept finding real bugs: the compounding-signal case for running multiple passes rather than accepting pass-one output
• Separate Your Build Model From Your Review Model: Codex as Adversarial Reviewer: the architectural separation between building and reviewing that makes reviewer input trustworthy
• Seven AI Reviewer Personas With a Cost Ledger, and a Budget Rule That Fires Them: cost accounting for when multi-reviewer cascades are worth running

dxdev LESSON · paste into your AI coding agent
LESSON: An outside reviewer can get the design exactly right and the transport exactly wrong, because your auth context isn't in the doc you sent
SOURCE: dxdev.com/blog/trpc-401-vs-rest-reviewer-right-substance-wrong-transport
WHAT HAPPENED: Two external AI reviewers, run in sequence so the second could build on the first's notes, converged on the correct design for a dashboard's aggregation endpoint, running its underlying queries in parallel, enforcing a strict timeout on the whole call, and returning partial data on timeout instead of failing the entire panel, with the second reviewer adding the partial-data behavior as a genuine improvement on the first's parallel-query-with-timeout shape. The second reviewer also recommended building the endpoint on the framework's typed RPC layer, which was wrong specifically for this surface: the dashboard authenticates with a distinct bearer-token scheme that the RPC layer's protected-procedure middleware doesn't recognize, so it would return a flat 401 before any of the correct handler logic ever ran, meaning every part of the design would have been right while nothing could ever call it. The fix kept the entire design substance unchanged, parallel queries, the timeout, the partial-data fallback, and only swapped which protocol it was built on, moving it to a plain REST route already living in the same authenticated request path the dashboard's bearer token actually clears; the same review session separately surfaced a specific file-line citation for an existing endpoint to reuse that also turned out to be wrong when checked against the actual 1,218-line source file, though the underlying endpoint itself was real and usable once verified.
THE RULE: An outside reviewer, human or AI, reasons from the artifacts you hand them and almost never has your private authentication context, which credential clears which gate. When a review recommends a specific transport or file location, separate the design substance, usually correct, from the delivery detail that depends on context you didn't supply, and verify any cited file or line against the real source before building on it.
CHECK MY CODE, then report PASS or FAIL with file:line for each:
  1. Any reviewer-recommended endpoint, transport, or protocol accepted without checking whether the specific surface's actual authentication method is compatible with that transport's auth middleware.
  2. Any reviewer suggestion accepted or rejected as a single atomic unit, rather than separating its design substance from its delivery-specific details that depend on private context the reviewer didn't have.
  3. Any specific file, line number, or symbol cited by an AI reviewer or assistant that was relied upon without opening the actual source to confirm it exists as described.
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.