Home Dashboard GitHub

Integrator DX: SDK recovery, unified error envelope, /v1/mcp guidance, load_shed 429

2026-08-28

apisdkmcprouting

LOCKSTEP TRACEABILITY MATRIX --- api_endpoints: [ "error responses now carry a top-level recovery mirror on every path", "GET|POST /v1/mcp -> 404 pointing at /v1/mcp/connect (was misleading 403)", "POST /v1/chat/completions x_br_routing.strategy populated (was null)", "load_shed -> 429 + typed retry_with_backoff recovery", ] sdk_methods_updated: ["sdk-ts + sdk-py error types surface recovery (read error.recovery, fallback top-level)"] mcp_tools_updated: ["none — /v1/mcp path guidance only; tools unchanged"] ---

What We Built

Readiness for a real customer (brainstorm) building against BR: five day-one papercuts a live integrator review flagged, closed.

  • SDK now surfaces recovery. The machine-readable recovery block existed on

the wire but both SDKs dropped it (they read only the top-level mirror, absent on most paths). TS + Py error types now read error.recovery (canonical) with a top-level fallback, so the documented recovery contract survives the SDK.

  • Unified error envelope. error.recovery is canonical on every path, and a

top-level recovery mirror is now emitted uniformly, so 400 and 401 no longer disagree on shape.

  • /v1/mcp stops lying. It returned a misleading 403 (permissions) for what

is a wrong-path problem; now a typed 404 whose recovery points at /v1/mcp/connect.

  • routing_strategy in the completion body. Was null while /v1/explain

reported it; now the body agrees with explain.

  • load_shed recovery contract. Load shedding already returns 429 (not a 503

outage); it now also carries retry_with_backoff so a client knows to back off.

Why It Matters

These are exactly the frictions a real integrator hits in the first hour. None were correctness bugs — they were the difference between "works if you already know the quirks" and "works from the docs." Paired with the deploy-rollback hardening, this is what makes BR ready to hand to brainstorm.

Lockstep Checklist

  • [x] API Routes: no new routes; response-shape/status/content changes only.
  • [x] TS SDK: error types surface recovery.
  • [x] Python SDK: error types surface recovery + code/request_id.
  • [x] MCP: /v1/mcp path guidance; tool contracts unchanged.
  • [x] llms: regenerated on build.

Open Follow-ups

  • Full error-envelope unification across every hand-rolled builder (rbac/killswitch) — larger sweep.
  • PyPI publish to npm parity (0.1.3) — needs a valid PYPI_TOKEN (operator).