Skip to content

[UX] Rate limit errors (429) should show user-friendly message with configurable retry instead of traceback #1826

@apoapostolov

Description

@apoapostolov

Problem

When hitting API rate limits (HTTP 429), Hermes currently displays a full traceback error to the user. This is a poor UX for a transient condition that the system should handle gracefully.

Current Behavior

ERROR:anthropic:Rate limit exceeded (429)
Traceback (most recent call last):
  File "/hermes/path/to/file.py", line 123, in function_name
    response = await client.chat(...)
anthropic.RateLimitError: Rate limit exceeded

Desired Behavior

  1. User-friendly message: Display a clear, concise message like:

    • "Rate limit reached. Waiting 30s before retry..." (with countdown)
    • "Rate limit active. Retry in 15s."
    • Or similar clean messaging
  2. Configurable automatic retry: Add config option(s) for rate limit handling:

    • retry.on_rate_limit: true (default)
    • retry.max_rate_limit_retries: 5 (default)
    • retry.rate_limit_backoff_base: 30 (seconds, default - exponential backoff)
    • retry.rate_limit_wait_max: 300 (max seconds to wait)
  3. Show progress: Display countdown or progress indicator during wait:

    • CLI: "Rate limit hit. Waiting 30s... [████░░░░░░] 12/30"
    • Gateway platforms: "Rate limit hit. Retrying in 30s..." (update as countdown progresses)
  4. Graceful failure: If retries exhausted or disabled, show clean error:

    • "Rate limit persisted after 5 retries. Please try again later."
    • No traceback for transient errors

Additional Notes

Priority

Medium - UX improvement, system already attempts retries internally

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions