Document proxy error codes and the X-Kernel-Proxy-Error header

[robertjamesprior]

Summary

The egress proxy sets X-Kernel-Proxy-Error to a typed code on every branded proxy-layer error response, and the error page itself instructs automation clients to read that header. Neither the header nor the codes appeared anywhere in the docs, so anyone building recovery on them had nothing to work from.

Adds proxies/errors.mdx covering:

• The X-Kernel-Proxy-Error header, and that the status is always 502 including for timeouts — so the header, not the status, is the signal.
• All eleven codes with what each one means and whether it is worth retrying. Meanings and retry guidance are taken from the proxy layer's own per-code presentation table, so the page matches what a user is already shown on the error page.
• A recovery pattern for the case that actually needs it: a person driving the browser through an embedded live view, where nothing re-navigates on their behalf and a transient provider failure becomes a dead end.
• A pointer to proxy_error browser telemetry for after-the-fact attribution.

origin_response_incomplete is deliberately excluded from the retryable set in the example, since the destination may already have acted on the request.

Testing

mint broken-links passes locally, which is what CI runs.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation and navigation only; no runtime, API, or auth changes.

Overview
Adds a Proxy Errors doc under the Proxies nav and links it from docs.json.

The new page documents X-Kernel-Proxy-Error: branded proxy-layer failures always return 502, so clients should use the header (not status) to classify errors—including WebSocket and subresource responses where the error page never shows.

It lists eleven typed codes with meaning and retry guidance, a TypeScript navigation retry pattern for live-view / human-driven sessions (with origin_response_incomplete excluded from auto-retry), and how proxy_error telemetry relates to the header (including gaps like unknown / raw_code).

^{Reviewed by Cursor Bugbot for commit 94d949e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

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

Project	Status	Preview	Updated
Kernel	🟢 Ready	View Preview	Sep 18, 2026, 10:04 PM

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

[cursor]

Risk Assessment: Very Low

Re-evaluated from the current diff (head 94d949ee). Risk is unchanged.

Changed files (2):

• proxies/errors.mdx — new Mintlify page documenting X-Kernel-Proxy-Error codes, retry guidance, a non-executed TypeScript example, and a telemetry note
• docs.json — adds the proxies/errors sidebar entry under the existing Proxies group

Why Very Low

• Documentation and nav config only; no application, API, auth, billing, or infrastructure code
• No shared runtime systems or production logic
• Small, easy-to-reason-about surface (static MDX + one nav string)
• This is product docs, not model/prompt instruction files
• No CODEOWNERS file in the repo, so codeowner review is not required by that mechanism

This automation already approved the current head. Approval stands; not re-approving.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 94d949e. Configure here.}

[cursor]

Gov recovery restates canonical guidance

Low Severity

The restricted_route_unavailable retry cell restates residential .gov targeting rules and the proxy health-check procedure rather than linking to those canonical pages. The inlined check also omits a .gov URL.

 

^{Triggered by learned rule: Single source of truth — no deep content duplication across pages}

^{Reviewed by Cursor Bugbot for commit 94d949e. Configure here.}