docs(errors): record typed-error adoption in the contracts reference

[ndycode]

Summary

Closes out audit roadmap §4.3 for the request layer (docs/audits/AUDIT_2026-06-10.md, PR #522) — with an honest result: the code portion is stale; the request layer already fully adopts the typed error contracts. This PR is the verification record plus the documentation the contract reference was missing.

Stacked on #524 (fetch-helpers split) since §4.3 was scoped against those files; merge #524 first.

What the verification found (no code changes needed)

• lib/errors.ts already provides the full taxonomy (CodexError base, CodexApiError, CodexAuthError, CodexNetworkError, CodexRateLimitError, StorageError, CodexUnavailableError + guard).
• token-refresh.ts already throws CodexAuthError with retryable/cause/context at all three failure sites; the catch site (refresh-guardian.ts) relies on instanceof CodexAuthError && !retryable — verified intact.
• The HTTP error-mapping contract is correctly fulfilled by normalized Response payloads (stable error.message/error.code), not thrown errors — typed classes deliberately don't apply there.
• The one bare TypeError (createCodexHeaders argument misuse) is a deliberate convention shared by all six dual-call helpers across the codebase, pinned by tests; converting one in isolation would fracture it.

Changes (docs only)

docs/reference/error-contracts.md (+10 lines): a "Typed Errors" subsection under the Fetch Helpers contract (documents CodexAuthError, its CODEX_AUTH_ERROR code, exact message, retryable/cause/context semantics, and that HTTP errors surface as Responses, not throws), and a note pinning the native-TypeError convention in the Options-Object Compatibility Contract.

Validation

• npm run typecheck
• 8 suites (fetch-helpers, quota-probe, index, index-retry, public-api-contract, chaos, documentation, errors): 419/419, identical to base via git-stash comparison
• Independently re-verified: documentation + errors suites, 61/61

Risk / Rollback

Docs-only; revert the single commit.

https://claude.ai/code/session_01XNtnkLbBiXZxfQQYLMpucB

---

Generated by Claude Code

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

this pr closes audit §4.3 by verifying that the request layer already fully uses the typed error hierarchy, then adding the missing reference documentation to docs/reference/error-contracts.md. no runtime behaviour changes.

• adds a "typed errors" subsection documenting CodexAuthError throw semantics, retryable/cause/context fields, and why http errors surface as Response objects instead of thrown errors.
• adds a note pinning the native TypeError convention for invalid named-parameter calls across the six dual-call helpers.

Confidence Score: 5/5

docs-only change; every claim in the new sections is verified against the live code, and no runtime paths are altered

the new documentation is factually accurate: error message matches the constant, code matches ErrorCode.AUTH_ERROR, retryable logic is correctly described for all three throw sites, cause/context mutually-exclusive presence is correctly qualified as 'where available', and the TypeError message in headers.ts matches the pinned example exactly

no files require special attention

Important Files Changed

Filename	Overview
docs/reference/error-contracts.md	the only file with net-new content in this pr; +10 lines accurately document CodexAuthError throw sites, retryable semantics, and the TypeError convention
lib/request/token-refresh.ts	carries the three CodexAuthError throw sites referenced by the new docs; code unchanged in this pr, all three sites verified against the documented message, code, and retryable logic
lib/request/fetch-helpers.ts	re-export barrel for the split request-layer modules; confirms http errors are returned as normalized Response objects, not thrown — consistent with new doc section
lib/request/headers.ts	contains the createCodexHeaders TypeError that is now pinned in the options-object compatibility contract; exact message matches doc
lib/request/error-classification.ts	entitlement/unsupported-model classification helpers; unchanged and consistent with docs describing http errors as Response payloads, not throws
lib/request/url-rewriting.ts	proxy and url-rewriting helpers; no changes relevant to the error contract documentation

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[refreshAndUpdateToken called] --> B{authSetter present?}
    B -- no --> E1[throw CodexAuthError\nretryable: false\nno cause, no context]
    B -- yes --> C[queuedRefresh token]
    C --> D{result.type}
    D -- failed --> E2[throw CodexAuthError\nretryable: isRetryableRefreshFailure\ncontext: refreshFailureReason + statusCode]
    D -- success --> F[authSetter.set persist]
    F -- throws --> E3[throw CodexAuthError\nretryable: isRetryableAuthSetterError\ncause: error]
    F -- ok --> G[mutate currentAuth in-place\nreturn currentAuth]

    style E1 fill:#f66,color:#fff
    style E2 fill:#f66,color:#fff
    style E3 fill:#f66,color:#fff
    style G fill:#6a6,color:#fff

Loading

_{Reviews (2): Last reviewed commit: "docs(request): pin refreshAndUpdateToken..." | Re-trigger Greptile}

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[coderabbitai]

Warning

Review limit reached

@ndycode, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 3 minutes and 10 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 03c1bd5f-55cc-4269-996b-82dea0c655c5

📥 Commits

Reviewing files that changed from the base of the PR and between 98d9819 and 4c0e0b7.

📒 Files selected for processing (6)

• docs/reference/error-contracts.md
• lib/request/error-classification.ts
• lib/request/fetch-helpers.ts
• lib/request/headers.ts
• lib/request/token-refresh.ts
• lib/request/url-rewriting.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/audit-24-error-contracts-request

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch claude/audit-24-error-contracts-request

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}