docs: triage "exceeded retry limit, last status: 429 Too Many Requests"

[Howard-Jerry]

Summary

• Add a practical triage table for the surfaced client error exceeded retry limit, last status: 429 Too Many Requests to the Codex retry diagnostics page. It teaches readers to distinguish three cases that look identical in that text: the OpenCodex main-account hard lock, an upstream ChatGPT plan window (5h/weekly), and a provider incident or transport failure.
• Real-world trigger: a machine that had stayed on a pre-fix(codex): retire main hard lock on authoritative absent 5h window #6287 build surfaced exactly this message on every turn while GET /api/settings still reported a carried blocked hard-lock state. The existing page covers retry advice semantics and reconnect rendering well, but a reader landing on this specific terminal text had no path from the message to the three checks that resolve it.
• Documents the verified release semantics from the closing note on Main-account hard lock never releases when the blocking 5h window stops being observed #6244 (fresh valid usage or validated window absence releases; an obsolete short-window block persists on pre-fix(codex): retire main hard lock on authoritative absent 5h window #6287 builds), the reset-credit tracking in [功能改进] 支持识别并使用 ChatGPT 赠送 Credits，修复周额度耗尽后的 429 拦截 #6845, and the official ChatGPT window/reset rules. Issue links use full URLs, matching the existing page style.

Verification

• Docs-only change: 1 file changed, 18 insertions (a single new section on the existing page; no front matter, sidebar or other docs touched).
• cd docs-site && bun install && bun run build — exit 0: 371 packages installed, 569 page(s) built, internal-links check checked 79312 internal links across 569 pages with no failures, pagefind + sitemap completed.
• Branch based on current dev (433764e9d).

Readiness

• Required local validation passed (commands and results above; scope: docs build + internal links).
• Branch on the latest dev commit (currently 433764e9d; will rebase if dev moves before review).
• All correct Codex and CodeRabbit findings resolved (will handle as findings arrive).
• Ready for review confirmation (will confirm once CI and review bots are clean).

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. (docs-only; no credentials or private paths included)

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• Required local validation passed; commands, results, and any full-suite exception are documented.

• I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

⏳ DRAFT

• review readiness checklist open (0/4 boxes ticked).

What to do

• Tick all four boxes in the PR description once you're done (currently 0/4).

Review readiness checklist

• ⬜ Required local validation passed; commands, results, and any full-suite exception are documented.
• ⬜ I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).
• ⬜ I resolved all correct Codex and CodeRabbit findings.
• ⬜ My PR is ready for review.

0/4 boxes ticked.

This PR stays in draft until every box above is ticked.

[Ingwannu]

Scoped documentation review of 32992c8c53a35e4b2ad94825b134ebdb942baceb:

The distinction between local admission, upstream quota and transport is useful. Please adjust the hard-lock table's instruction "Release it with a validated usage refresh" to "Refresh usage to reevaluate the lock; it releases only when fresh evidence is below the applicable thresholds or validates that the previously blocking window is absent." getMainAccountHardLockStatus in src/codex/main-account-hard-lock.ts still returns blocked for a fresh reading at/above its threshold. A refresh therefore is not a guaranteed unlock. Disabling the policy is a deliberate operator override, not restoration of upstream capacity.

Keep the upstream row explicitly plan-dependent and prefer the returned account windows/reset times: current official pricing guidance distinguishes plan-specific five-hour/weekly limits. The app-server reset contract also requires refreshing limits after a reset and allows a no-eligible-window result; spending a credit is not itself evidence that every limit cleared.

The PR remains Draft with incomplete author readiness; this COMMENT is not approval. I did not run a new docs build, account refresh, credit redemption or paid/live request.

[lidge-jun]

Thanks @Howard-Jerry! This change landed on dev in #7065 (1edd55a), carried unchanged in its own commit with you credited in a Co-authored-by trailer. The fork PR never got the repository's main CI, so I carried it onto an upstream branch to run it. Closing this PR because the carry superseded it.