openclaw - 💡(How to fix) Fix [Bug]: Subscription quota limit ("You've hit your limit") classified as billing error, blocks model fallback [1 participants]

When using a Claude subscription (setup-token / Claude Code OAuth) and the usage quota is exhausted, OpenClaw receives an error like: Claude Code returned an error result: You've hit your limit · resets 6pm (UTC) This error is classified as a billing failure, which puts the auth profile into a long disabledUntil state. Because billing-disabled profiles use a long backoff (not FailoverError), the configured fallback models are never attempted — the agent simply fails until the window resets.

1. Subscription quota is exhausted → error classified as billing
2. Config escape hatch (nice-to-have): allow users to define custom error text patterns that should be treated as failover-worthy:

TL;DR

Update the classifyFailoverReason function to correctly classify quota exhaustion errors as quota instead of billing to trigger failover to fallback models.

Guidance

• Review the classifyFailoverReason function to detect the specific error message pattern "You've hit your limit" or "resets at" and classify it as a quota error.
• Consider adding a config option failoverPatterns to allow users to define custom error text patterns that should trigger failover.
• Verify that the fallback models are correctly configured and prioritized in agents.defaults.model.fallbacks.
• Test the updated classification and failover behavior with a simulated quota exhaustion error.

Example

auth:
  failoverPatterns:
    - "You've hit your limit"
    - "resets at"

This example shows how the failoverPatterns config option could be used to define custom error patterns.

Notes

The suggested fix assumes that the classifyFailoverReason function is the primary cause of the issue. Additional logging or debugging may be necessary to confirm this.

Recommendation

Apply the workaround by updating the classifyFailoverReason function to correctly classify quota exhaustion errors, as this will allow the fallback models to be attempted when the primary model is rate-limited.