Found while landing #12342 (PR #12387), which narrowed the two Error Handling
examples that card names. Zone 2c of that card's dispatch asked for a count of
how many blocks on the page have the shape. The answer is three, not two.
The third one
content/docs/api/client-sdk.mdx, inside the large API-surface tour fence
(around line 431 on main at the time of writing):
// A flow that does not run REJECTS — it does not resolve with an inner
// `{ success: false }`. Branch on `err.code`, not on the resolved value:
try {
await client.automation.execute('order_approval', { params: { orderId } });
} catch (err) {
err.httpStatus; // 409 | 422 | 400 | 404
err.code; // 'FLOW_DISABLED' | 'FLOW_NO_START_NODE' | 'FLOW_FAILED'
err.details?.errorMessage; // the flow author's own text, on a FLOW_FAILED
err.details?.summary; // which node failed, on a FLOW_FAILED
}Same defect as #12342: under strict — which implies
useUnknownInCatchVariables, the tsc --init default since TS 4.4 — err is
unknown, so all four reads are TS18046: 'err' is of type 'unknown'. A
reader copying this into their own project gets a compile error, and the
paragraph above the block is explicitly instructing them to branch on err.code.
Why it was left out of #12342
That card names two blocks and its dispatch ruling scoped the fix to exactly
those two, so this one was deliberately not touched. It also differs in kind:
the two Error Handling blocks are short, standalone examples, while this one is
a fragment inside a ~150-line multi-section tour fence whose subject is the
whole client surface, not error handling. Narrowing it means either introducing
a guard into the middle of the tour or moving the flow-rejection example out of
it — a shaping question, not a mechanical edit, which is why this is its own
card.
The narrowing that is true here
PR #12387 established, by reading the client's request seam
(packages/client/src/index.ts, the !res.ok branch), what the SDK actually
attaches to the Error it throws: httpStatus always, code / category /
retryable / fields only when the server sent them, details always. Whoever
takes this card should reuse that same shape rather than re-deriving it, and
should NOT narrow to the exported StandardError — see PR #12387's body for the
three measured reasons that type does not describe the thrown object.
Not in scope here
os:check markers. This page's marker coverage is a separate question and
this card does not touch it.- The page's TS2304 continuation convention (Quick Start establishes
client
once) — deliberate and documented on the page.
Found while landing #12342 (PR #12387), which narrowed the two Error Handling
examples that card names. Zone 2c of that card's dispatch asked for a count of
how many blocks on the page have the shape. The answer is three, not two.
The third one
content/docs/api/client-sdk.mdx, inside the large API-surface tour fence(around line 431 on
mainat the time of writing):Same defect as #12342: under
strict— which impliesuseUnknownInCatchVariables, thetsc --initdefault since TS 4.4 —errisunknown, so all four reads areTS18046: 'err' is of type 'unknown'. Areader copying this into their own project gets a compile error, and the
paragraph above the block is explicitly instructing them to branch on
err.code.Why it was left out of #12342
That card names two blocks and its dispatch ruling scoped the fix to exactly
those two, so this one was deliberately not touched. It also differs in kind:
the two Error Handling blocks are short, standalone examples, while this one is
a fragment inside a ~150-line multi-section tour fence whose subject is the
whole client surface, not error handling. Narrowing it means either introducing
a guard into the middle of the tour or moving the flow-rejection example out of
it — a shaping question, not a mechanical edit, which is why this is its own
card.
The narrowing that is true here
PR #12387 established, by reading the client's request seam
(
packages/client/src/index.ts, the!res.okbranch), what the SDK actuallyattaches to the
Errorit throws:httpStatusalways,code/category/retryable/fieldsonly when the server sent them,detailsalways. Whoevertakes this card should reuse that same shape rather than re-deriving it, and
should NOT narrow to the exported
StandardError— see PR #12387's body for thethree measured reasons that type does not describe the thrown object.
Not in scope here
os:checkmarkers. This page's marker coverage is a separate question andthis card does not touch it.
clientonce) — deliberate and documented on the page.