fix(router): document BCK.ROUTER.0010 and 0011 — two codes an agent must never auto-retry

[r-marques]

Independent of #289 and #290 — branches off main, touches different files, merge in any order.

The gap

Scope grew after review: this now documents 0010 and 0011. aaitor caught that 0011 (402, 3-D Secure) landed on origin/main on 2026-08-11 — the same day this PR was authored — and is the more reachable of the two: 0010 needs a Nevermined-side regression to fire at all, 0011 fires on normal operation of any 3DS card, with the same mint-and-abandon credential trap. Folded in rather than deferred.

BCK.ROUTER.0010 landed in nvm-monorepo on 2026-08-07 (fdf057ffd, the #2191 fee accrual) and is documented nowhere — not in SKILL.md, not in references/errors.md (whose table is headed "Every Router code" and stops at 0009), not on the docs site, not in any of the four IDE rule files.

Found while shipping #289, by re-verifying the skill's facts against the current API rather than the state they were authored against.

Why this one matters more than a missing table row

It's the most retry-dangerous code the Router can return, and the danger isn't visible from the status alone. It's a 500 — and 0006, our only other 500, is the single entry in every table marked retryable. An agent that generalises "retry the 5xx" lands on exactly the wrong behaviour:

• No budget was reserved and no payment record was written.
• But a payment credential was already minted — on the card rail, a real Stripe Shared Payment Token.
• So requestId cannot protect you: idempotency is enforced against the payment record, and there isn't one. The retry is treated as a brand-new purchase and mints another credential.
• And the cause is a deterministic defect in the rail's approxCents derivation, not a transient blip — so the retry fails identically.

The upstream hint says DO NOT BLIND-RETRY in capitals. None of that reached a single reader.

What changed

0010 added to all seven hand-authored surfaces, with the "don't generalise to retry 5xx" warning stated explicitly rather than left implicit in the retryable column:

File
skills/nevermined-router/SKILL.md	table row + a named anchor, and rule 4 now warns against generalising
skills/nevermined-router/references/errors.md	table row + a full subsection on what it leaves behind
products/router/guardrails.mdx	table row + a <Warning>
.cursor / .windsurf / .clinerules / .amazonq rule files	one compact bullet each

Verification

• Every BCK.ROUTER.* code and HTTP status re-checked against libs/helpers/src/lib/output/api-errors.ts on nvm-monorepo origin/main. 0001–0009 all still match the docs exactly. 0010 was the only missing one. Corrected: BCK.ROUTER.0011 (402, 3-D Secure) landed on origin/main the same day this was authored, so that enumeration was true when run and stale when published. Both are now documented here — see below.
• Windsurf's 6,000-character limit respected: 5,240 → 5,420 characters (5,292 → 5,474 bytes — the file has multi-byte em dashes, and the limit is stated in characters).
• No changed file is gitignored (the docs#267 .cursor trap).
• JSX balance checked on guardrails.mdx.

development-guide/api-errors/codes.mdx is deliberately not touched — it's generated and synced from nvm-monorepo, and #287 already carries 0010.

⚠️ mintlify broken-links can't run — the bare <token> in that same generated codes.mdx aborts the parse site-wide. Pre-existing; source fix is nvm-monorepo#2805.

Five more drifts found, filed separately

The same sweep turned up five further gaps between the skill and today's API. They're tracked in https://github.com/nevermined-io/nvm-monorepo/issues/2854 rather than piled in here — none is currently wrong for a live user, whereas 0010 is a live hazard now.

BCK.ROUTER.0011 — added after review

402, category: business, retryable: false. The card issuer demands 3-D Secure and the Router has no human at a browser to complete it, so nothing was charged and the seller never received a usable credential.

Why it must not be auto-retried, per its own hint: 3DS is often mandated per charge by industry rules, so every attempt re-demands it, and each attempt creates a fresh single-use card credential that is then abandoned — each expiring at min(merchant's quoted expiry, Delegation expiry, 89 days). A later attempt may succeed, but that is a human decision, not a loop.

It is also distinct from both other 402s, which the docs now say explicitly: 0003 is your cap, 0009 is a card refused for lack of funds. Here the card is fine — it simply hasn't been authenticated for this charge.

The reframing that came with it (aaitor's second point, and the better lesson): the takeaway isn't "0010 is the exception to retry the 5xx" — it's that the HTTP status doesn't tell you whether to retry. 0010 is a 500 you must not retry; 0011 is a 402 that reads like a routine payment error and equally must not be. A reader who internalises "the one status trap is the 500" walks straight into the 402 one. That is now stated in SKILL.md rule 4 and in the guardrails.mdx Warning.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Nevermined	🟢 Ready	View Preview	Aug 11, 2026, 2:51 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[r-marques]

⚠️ The PR head moved during this review (9d90d1a410d4 → 97457ceba374). Findings were produced against 9d90d1a410d4; inline anchors were re-validated against 97457ceba374, so double-check the placement of any comment that looks off.

🤖 Automated PR review — ✅ Ready to merge

Panel review of the BCK.ROUTER.0010 documentation sweep. The four load-bearing claims were verified against nvm-monorepo origin/main at the call-path level, not from the error-registry hint text — which matters, because the PR's central warning depends on an ordering the hint asserts but does not prove.

The trace, in apps/api/src/router/router.service.ts inside createPayment: the idempotency pre-check (findOne({ userId, requestId }), backed by a DB partial-unique index — both keyed on the payment record) → handler.prepare(...) → recipient scope → await prepared.sign(), which mints the credential → quoteRouterFee(...) at line 291, which is where parseMerchantCents throws 0010 → only then RouterPaymentEntity.create and the transaction doing atomicCapDecrement + save. So at the throw: credential exists, cap untouched, row never written — and a retry with the same requestId sails past step 1 and mints again. The warning is right, and right for the reason it states.

What I reviewed

• Diff range origin/main...HEAD — 7 files, +42/−1 at review time (9d90d1a).
• Panel: pr-review-toolkit:code-reviewer, plus independent verification against nvm-monorepo origin/main.
• Enumerated every BCK.ROUTER.* and BCK.CATALOG.* in libs/helpers/src/lib/output/api-errors.ts: exactly ROUTER.0001–0010 and CATALOG.0001–0003. No other undocumented code, and all ten existing rows match the source on status and retry flag, in both changed tables.
• Sweep completeness checked on the stricter criterion — not "which files have a table" but "which files state the retry policy", since that is where an agent forms the wrong reflex. Both criteria give the same answer here. quickstart.mdx was correctly left alone: it is a real table, but an explicitly curated subset ("the three you're most likely to meet") that links here for every code.
• development-guide/api-errors/codes.mdx correctly untouched — generated by sync-errors-docs.yml.
• .windsurf/rules/nevermined-router.md at 5,420 characters, under its 6,000 limit.

Findings — 1 Medium, 4 Low, all folded in before merge (ff9a24f, 97457ce):

1. Medium — the card-rail reassurance was understated. The text said the stranded credential "auto-expires" and that "there's no cleanup for you to do". Verified: SPT_MAX_EXPIRY_SECONDS is 89 days, the expiry is min(challenge, delegation, now + 89d), and there is no deactivate or revoke path anywhere under apps/api/src/router/ — so the token is stranded, not merely short-lived. Now states the bound and says plainly it can't be cleaned up from outside.
2. Low → improvement. Added the rail split the review surfaced from source: on the crypto rails the credential never leaves the Router process on this path, so no funds can move and nothing is at risk. Only the card rail strands anything. That is the difference between alarming and actionable, and it is the strongest true statement available here.
3. Low — guardrails.mdx carried the weakest signal of the three surfaces: a bare No in the Retry? column while SKILL.md and errors.md said No — never blind-retry. All three now match.
4. Low — "Unlike 0006" was apples-to-oranges. 0006 has exactly one throw site (router.service.ts:928, a read-only summary method), so it is never raised by a payment — meaning on the paying path 0007 is the only retryable code at all. Now said outright.
5. Low — 0010 is currently unreachable. All three rails feed parseMerchantCents a pre-validated numeric value, so seeing it is a Nevermined-side regression. Stated, to push readers toward "report" rather than "handle".

An open question about whether Stripe's shared_payment.issued_token.* webhooks reach the seller became moot: the revised wording rests on "there is no revoke path, so it stands until it expires", which is true either way.

Note on head drift: the PR head has moved since the diff above — deliberately. The review found the issues, and the two follow-up commits are the fixes. Re-verified against the new text.

Known follow-up, not a blocker: codes.mdx still says "BCK.ROUTER — 9 codes" until the sync-errors-docs.yml PR lands from nvm-monorepo (#287 carries 0010).

Verdict: ✅ Ready to merge — 0 blockers, 0 outstanding should-fix, 0 outstanding nits.

[aaitor]

Strong, well-researched PR — I verified all seven load-bearing 0010 claims against nvm-monorepo origin/main at the call-path level (not the hint text), and every one holds. The 0010 documentation itself is accurate and I'd merge it as written.

One blocker, and it's cheap. A same-class Router hazard, BCK.ROUTER.0011 (402, 3-D Secure), landed on origin/main on 2026-08-11 (7096629f9, #2765) — the same day this PR was authored, which is why the sweep missed it. It's undocumented in every surface this PR touches, it is more reachable than 0010 (it fires on any normal 3DS card, whereas 0010 needs a Nevermined-side regression by this PR's own admission), and it carries the identical mint-and-abandon card-credential trap. That also makes the PR body's "0010 was the only missing one" inaccurate — on origin/main there are now two. Fold it in (recommended) or defer with a tracking issue and soften the claim; either clears the gate. Full fix text is inline on references/errors.md.

Verification I ran

• Read all 8 changed files in post-PR state (docs/document-router-0010, HEAD 1dc03d8). CI green (2/2).
• Call-path trace on nvm-monorepo origin/main: idempotency pre-check findOne({userId, requestId}) → 0002 409 carrying the original paymentId (router.service.ts:213-220; 0002 is httpStatus 409 in api-errors.ts); prepared.sign() mints at :327; quoteRouterFee at :358 → parseMerchantCents throws 0010 (router-fee.ts:141) before the record write (:380+) and atomicCapDecrement (:408). So at the throw: credential exists, cap untouched, no record → a same-requestId retry sails past the pre-check and re-mints. Matches the diff exactly, including the 867a863 "409, not the resource" correction.
• 0006 has a single throw site — the payments-summary read (:1615), never the paying path → "on the paying path 0007 is the only retryable code" is exact.
• Card-rail facts corroborated by the router-fee.ts:188 "durable Stripe SPT / burnt custodial signature" comment and, independently, by the 0011 hint (same SPT, same min(challenge, delegation, 89 days), no revoke path).
• Enumerated every BCK.ROUTER.* / BCK.CATALOG.* on origin/main: ROUTER.0001–0011 + CATALOG.0001–0003. 0001–0009 match the docs exactly; 0010 is added here; 0011 is missing everywhere (hand-authored and generated codes.mdx), and #2854's five gaps do not include it.
• .windsurf file 5,420 chars / 5,474 bytes — under the 6,000-char limit. guardrails.mdx JSX balanced (2/2 <Warning>, 2/2 <Note>). All four IDE-rule bullets identical.
• Over-engineering / leanness pass (/ponytail-review): lean already, ship — net 0 removable lines. The three-tier depth (SKILL quick / references deep / guardrails site) matches the skill's existing structure; the four IDE bullets are distinct deliverables, not duplication.
• AGENTS.md / .github/copilot-instructions.md carry no Router error surface on this branch (they arrive via #289) → correctly untouched.

For the next PR in the sweep: #2854's process note is right — a CI check diffing api-errors.ts's BCK.ROUTER.* codes against the skill's table would have caught 0010 and 0011 the day each landed. 0011 is the second miss in a week from the same manual-snapshot gap; worth prioritising that guard.

[r-marques]

@aaitor — you're right, and it was worth blocking on. Folded in rather than deferred (234051a).

I verified 0011 against origin/main before acting: 402, category: business, retryable: false, landed 2026-08-11 in 908bae1de. My enumeration of "exactly 0001–0010" was true when I ran it and stale by the time it was published — which is the same manual-snapshot failure this PR exists to fix, so it's a fair catch on the process as well as the content.

Your point that 0011 is the more dangerous of the pair is the one that decided it for me. 0010 needs a Nevermined-side regression to fire at all — this PR says so in as many words. 0011 fires on normal operation of any 3DS card, and carries the identical mint-and-abandon trap.

And your second point was the better framing, so I took it over my own. I had written the lesson as "0010 is the exception to retry the 5xx". That's too narrow: the real lesson is that the HTTP status doesn't tell you whether to retry, and 0011 is precisely the mirror-image trap — a 402 that reads like a routine payment error and equally must not be auto-retried. A reader who internalises "the one status trap is the 500" walks straight into the 402 one. That reframing now sits in SKILL.md rule 4 and in the guardrails.mdx Warning, not just as an extra table row.

What landed

• All seven surfaces on this branch: SKILL.md (row + prose + rule 4), references/errors.md (row + a full subsection mirroring 0010's), products/router/guardrails.mdx (row + extended Warning), and one bullet in each of the four IDE rule files. Windsurf is at 5,666 / 6,000 characters.
• errors.md also states what your suggested text didn't quite cover: 0011 is distinct from both other 402s — 0003 is the cap, 0009 is a card refused for lack of funds, and here the card is fine and simply unauthenticated. That distinction is drawn explicitly in the code's own hint and is exactly the confusion an agent would otherwise make.
• The condensed sections in AGENTS.md / .github/copilot-instructions.md carry it too, via feat(skills): distribute the skills as Claude Code plugins, document ClawHub, and give Copilot/Codex the Router #289 — they gain the Router error table in that PR, so they'd have shipped with the same gap.
• PR title and body corrected: the "0010 was the only missing one" claim is struck rather than quietly edited.

On the tracking guard — agreed, and 0011 being the second miss in a week from the same gap is the argument. Recorded on https://github.com/nevermined-io/nvm-monorepo/issues/2854, which now also carries 0011 (it wasn't in the original five, as you noted) plus a seventh drift item found while rebasing: docs#288 improved the 0009 description on the docs site but not in the skill, so the skill still tells an agent to expect 0009 on the x402 rail where it cannot occur.

Ready for another look.

[aaitor]

✅ Approving — the 0011 gap is fully closed. The prior HIGH is resolved across every Router surface, re-verified against nvm-monorepo origin/main, and the one hard constraint (Windsurf's char limit) still holds. One LOW left inline — an orphaned anchor the rule-4 reframe left behind — which does not gate.

Re-review of 234051ad0 (prior review was 1dc03d8)

Resolved — my prior HIGH (BCK.ROUTER.0011 undocumented across all surfaces):

• Added to all seven surfaces: a table row + a full mirror subsection in references/errors.md, SKILL.md and guardrails.mdx, and a 3-line bullet in each of the four IDE rule files — consistent wording throughout.
• Every 0011 claim matches the api-errors.ts 0011 hint on origin/main: card-rail 3-D Secure, no money moved, seller got no usable credential, per-charge 3DS re-demand mints-and-abandons a fresh single-use SPT, min(challenge, Delegation, 89 days) expiry, may succeed on a later human-driven attempt.
• You improved on my suggested text by stating 0011 is distinct from both other 402s (0003 = cap, 0009 = funds) — I checked that against the hint; it's accurate.
• The guardrails.mdx Warning now leads with 0010 (the 500 case), adds 0011 as its 402 mirror, and closes on the right general rule — HTTP status doesn't tell you whether to retry; read the code — echoed in SKILL.md rule 4. Exactly the reframe my second comment asked for.

Verification I ran

• Diffed 234051ad0 against my prior findings; read every changed file in post-commit state. CI green (Mintlify deploy + link-rot pass; vale skipped).
• Re-verified 0011 against api-errors.ts (BCK.ROUTER.0011, httpStatus 402) on origin/main. Full Router set is now documented end-to-end: 0001–0011.
• Windsurf budget re-checked: 5,666 chars / 5,724 bytes — still under the 6,000-char limit (334 headroom). The new bullet fit.
• JSX unchanged — the 0011 paragraph is plain text inside the existing <Warning>, so balance stays 2/2.
• Over-engineering / leanness pass: the only thing to trim is the now-dead #never-retry-0010 anchor (LOW, inline). Otherwise net 0 removable.

Cosmetic, non-blocking: the PR body's "0010 was the only missing one" line is now doubly stale — worth a one-line tweak when you merge, but it isn't shipped content.

Nice work — this is a genuinely complete Router error-doc sweep now.