Skip to content

Fix misleading rate limit message and improve verbose logging for /limits#1447

Merged
konard merged 6 commits intomainfrom
issue-1446-2d8af8e9f8d5
Mar 20, 2026
Merged

Fix misleading rate limit message and improve verbose logging for /limits#1447
konard merged 6 commits intomainfrom
issue-1446-2d8af8e9f8d5

Conversation

@konard
Copy link
Copy Markdown
Contributor

@konard konard commented Mar 19, 2026 •
edited
Loading

Summary

Fixes #1446

  • Fix misleading "Retry after: 0s" message: When the Anthropic Usage API returns HTTP 429 with retry-after: 0, the message now shows "Try again later." instead of the misleading "Retry after: 0s". For meaningful retry-after values, shows proper reset time like "Resets in 5m (Mar 19, 8:00pm UTC)"
  • User-friendly rate limit message: Changed from technical "Rate limited by Claude Usage API." to clearer "Claude Usage API access has reached rate limit."
  • Cache 429 rate-limit errors: Previously only successful responses were cached (20-min TTL). Now rate-limit errors are also cached to prevent hammering an already-rate-limited endpoint
  • Enhanced verbose logging: Full request URL, sanitized headers, all response headers, and response body are now logged in verbose mode for easier debugging of API issues

Root Cause

The Anthropic /api/oauth/usage endpoint has a known issue where it returns persistent 429 with retry-after: 0 (anthropics/claude-code#30930). Our code was displaying this misleading value directly to users.

Changes

File Change
src/limits.lib.mjs New formatRetryAfterMessage() function, user-friendly error message, enhanced verbose logging, 429 caching
tests/limits-display.test.mjs 12 new tests for formatRetryAfterMessage() (total: 50 tests, all passing)
docs/case-studies/issue-1446/ Case study with root cause analysis and upstream issue references
.changeset/ Patch changeset for release

Test plan

  • All 50 existing + new tests pass (node tests/limits-display.test.mjs)
  • formatRetryAfterMessage(null) → " Try again later."
  • formatRetryAfterMessage('0') → " Try again later." (the key fix)
  • formatRetryAfterMessage('300') → " Resets in 5m (Mar 19, 8:00pm UTC)"
  • formatRetryAfterMessage('3600') → " Resets in 1h 0m (...)"
  • HTTP-date format support
  • 429 caching prevents repeated API calls
  • Verbose mode logs request/response headers with sanitized Authorization
  • Rate limit message uses user-friendly phrasing

🤖 Generated with Claude Code

@konard
Initial commit with task details
9ab9272 
Adding .gitkeep for PR creation (default mode).
This file will be removed when the task is complete.

Issue: #1446
@konard konard self-assigned this Mar 19, 2026
konard and others added 3 commits March 19, 2026 19:33
@konard @claude
Fix misleading rate limit message and improve verbose logging for /li…
6fda93d 
…mits

- Replace misleading "Retry after: 0s" with proper reset time formatting
  (e.g., "Resets in 2m 30s (Mar 19, 8:00pm UTC)") or "Try again later."
  when retry-after is 0/missing
- Add full request/response verbose logging: URL, sanitized headers,
  response headers, and response body
- Cache 429 rate-limit errors to prevent repeated requests to a rate-limited
  endpoint (uses same 20-minute TTL as successful responses)

Fixes #1446

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@konard @claude
Add tests for formatRetryAfterMessage and case study for issue #1446
5b0b20b 
- Add 12 tests for formatRetryAfterMessage covering null, 0, negative,
  seconds, minutes, hours, HTTP-date, and integration with formatUsageMessage
- Add case study with timeline, root cause analysis, upstream issue references,
  and community workarounds documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@konard @claude
Add changeset for /limits rate limit message fix
eff731b 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@konard konard changed the title [WIP] We should provide full request and response for /limits command in --verbose mode, so we can understand what exactly happening Fix misleading rate limit message and improve verbose logging for /limits Mar 19, 2026
@konard konard marked this pull request as ready for review March 19, 2026 19:36
@konard
Copy link
Copy Markdown
Contributor Author

konard commented Mar 19, 2026

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

  • Public pricing estimate: $3.497453
  • Calculated by Anthropic: $2.313095 USD
  • Difference: $-1.184358 (-33.86%)

🤖 Models used:

  • Tool: Claude
  • Requested: opus
  • Main model: Claude Opus 4.6 (ID: claude-opus-4-6, Anthropic, cutoff: 2025-05)
    📎 Log file uploaded as Gist (1511KB)
    🔗 View complete solution draft log

Now working session is ended, feel free to review and add any feedback on the solution draft.

@konard
Copy link
Copy Markdown
Contributor Author

konard commented Mar 19, 2026

✅ Ready to merge

This pull request is now ready to be merged:

  • All CI checks have passed
  • No merge conflicts
  • No pending changes

Monitored by hive-mind with --auto-restart-until-mergeable flag

@konard
Copy link
Copy Markdown
Contributor Author

konard commented Mar 19, 2026 •
edited
Loading

Can we rephrase Rate limited by Claude Usage API. to something more user friendly like Claude Usage API access has reached rate limit or something similar? So user without understanding the system can understand what is going on.

@konard konard marked this pull request as draft March 19, 2026 19:51
@konard
Copy link
Copy Markdown
Contributor Author

konard commented Mar 19, 2026

🤖 AI Work Session Started

Starting automated work session at 2026-03-19T19:51:18.886Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait for the session to finish, and provide your feedback.

@konard @claude
Rephrase rate limit message to be more user-friendly
d23cb72 
Change "Rate limited by Claude Usage API." to "Claude Usage API access
has reached rate limit." per PR review feedback for clearer messaging.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@konard konard marked this pull request as ready for review March 19, 2026 19:52
@konard
Copy link
Copy Markdown
Contributor Author

konard commented Mar 19, 2026

Good suggestion! Updated the message from "Rate limited by Claude Usage API." to "Claude Usage API access has reached rate limit." in commit d23cb72. All 50 tests pass.

@konard
Copy link
Copy Markdown
Contributor Author

konard commented Mar 19, 2026

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

  • Public pricing estimate: $0.964363
  • Calculated by Anthropic: $0.529197 USD
  • Difference: $-0.435166 (-45.12%)

🤖 Models used:

  • Tool: Claude
  • Requested: opus
  • Main model: Claude Opus 4.6 (ID: claude-opus-4-6, Anthropic, cutoff: 2025-05)
    📎 Log file uploaded as Gist (442KB)
    🔗 View complete solution draft log

Now working session is ended, feel free to review and add any feedback on the solution draft.

@konard
Copy link
Copy Markdown
Contributor Author

konard commented Mar 19, 2026

✅ Ready to merge

This pull request is now ready to be merged:

  • All CI checks have passed
  • No merge conflicts
  • No pending changes

Monitored by hive-mind with --auto-restart-until-mergeable flag

@konard konard merged commit 60bcf77 into main Mar 20, 2026
21 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@konard konard

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

We should provide full request and response for /limits command in --verbose mode, so we can understand what exactly happening

1 participant

@konard