[sjungwon03]

Closes #558. Refs #116; Jev #7 remains unresolved.

A stream:true request rejected by a registered provider with429/503 previously became502 without its safe Retry-After, even before any client SSE started. Text/function consumers now retain bounded metadata from those observed HTTP rejections. After required failed-attempt usage and outcome audit, /api/v1 returns that JSON status/matching numeric error.code; /v1 keeps502/symbolic upstream_failed. Both may return canonical integer-seconds Retry-After, including zero. Missing/invalid hints do not suppress a valid status.

Once streaming starts, HTTP200 and existing generic safe SSE errors remain unchanged: discard upstream status/hints, retain interruption-audit failure semantics and withhold final usage/DONE. Local/persistence/unclassified exceptions and other statuses cannot inherit metadata. Rejected-body cancellation, IAM/limits/registered destinations, possible-billing/missing usage and fallback eligibility remain intact. No new ledger/audit fields or raw provider body/header forwarding.

Plan: 558-prestream-errors. Contract: pre-stream errors.

Validation:

• TDD red before production changes:144 cases,104 expected collapsed-status/missing-hint failures,40 passes. Minimal consumer/HTTP projection changes made all144 pass.
• Actual pinned OpenAI/OpenRouter/AI SDK client probes:96 passed across both bases/all four routes/text-function modes, retries disabled and one upstream attempt.
• Final integrated focused selection:711 passed, including all268 new cases. Includes malformed hints, unrelated statuses, admission, delayed/failed usage/outcome audit, post-frame/unclassified isolation, interruption-audit failure and managed fallback outcome isolation.
• The first full gate identified9 existing SDK assertions of the intentionally superseded compatible pre-stream429-to502 mapping. Updated only those pre-stream expectations; legacy502, invalid-response502 and midstream/persistence/privacy assertions remain. All four affected SDK suites pass in the integrated selection.
• Final npm run check:8,213 total,8,212 passed, zero failures/cancellations, one optional external PostgreSQL skip (~244sec). Typecheck, lint, document/link/fixture-secret checks and all six offline source-integrity checks passed.
• Existing42 lint warnings/65 infos remain unchanged. Final document/whitespace/CLAUDE.md symlink checks passed. Six source pins, dependencies, migrations and operational accounting/audit schemas are unchanged.

Risks/limits: clients may change retry/backoff with distinguishable429/503/Retry-After; probes disable retries and certify delivery only. Registered observed rejections remain responseStarted:true, so this adds no automatic fallback, retry/sleep or free-retry guarantee. Exact provider causes, broader status/date/402 and streaming error parity, live providers and full #116 remain open. Six source pins, dependencies and storage remain unchanged.

[sjungwon03-ai]

Review summary

Verdict: Approved

• Reviewed: Bounded pre-stream 429/503 and Retry-After capture across all eight response consumers, legacy/compatible JSON projection, persistence gating, cancellation, fallback isolation, post-start SSE behavior, privacy, and SDK regressions.
• Checks: All three GitHub checks passed; locally, all 711 focused tests, TypeScript checking, documentation/link/fixture-secret validation, six offline schema-integrity checks, and git diff --check passed.