openclaw - ✅(Solved) Fix Feature request: overloaded_error should trigger model fallback, not just auth token rotation [1 pull requests, 1 participants]

Q: Expected behavior

After N retries of `overloaded_error` on the same model, fall through to the next model in the fallbacks chain.

openclaw2026-03-31 21:42:31

ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

GitHub issue URL

Helpful · Quick feedback

GitHub stats

openclaw/openclaw#58572•Fetched 2026-04-08 02:00:51

View on GitHub

Comments

Participants

Timeline

Reactions

Author

Forgely3D

Participants

Forgely3D

Timeline (top)

referenced ×3closed ×1cross-referenced ×1locked ×1

Error Message

Gateway logs show repeated:

failoverReason: "overloaded"
model: "claude-sonnet-4-6"
providerErrorType: "overloaded_error"

Every ~10s, never falling back to the next model.

PR fix notes

PR #58707: fix: escalate to model fallback after rate-limit profile rotation cap

Repository: openclaw/openclaw
Author: Forgely3D
State: closed | merged: True
Link: https://github.com/openclaw/openclaw/pull/58707

Description (problem / solution / changelog)

Problem

When a model returns rate_limit_error (HTTP 429), OpenClaw currently:

✅ Rotates between auth tokens (profiles) — good when the limit is per-key
❌ Does NOT fall back to the next model in the fallbacks chain

If claude-sonnet-4-6 has a per-model quota (e.g. Anthropic's Sonnet-only usage tiers), all profiles share that same model quota. Rotating between them loops forever without ever falling through to claude-opus-4-6 or gpt-5.4.

This is the rate_limit equivalent of #58348 (overloaded escalation).

Observed behavior

Gateway logs show repeated:

decision=rotate_profile reason=rate_limit provider=anthropic/claude-sonnet-4-6

Every ~10s across all profiles, never falling back to the next model.

Fix

Apply the same rotation-cap pattern from #58348 (overloadedProfileRotations) to rate-limit errors:

Add auth.cooldowns.rateLimitedProfileRotations config (default: 1)
After N profile rotations on rate_limit, throw FailoverError → triggers cross-provider model fallback
Add resolveRateLimitProfileRotationLimit helper in run/helpers.ts

Changes

src/agents/pi-embedded-runner/run.ts — rate-limit rotation cap check before advanceAuthProfile()
src/agents/pi-embedded-runner/run/helpers.ts — resolveRateLimitProfileRotationLimit + default constant
src/config/types.auth.ts — rateLimitedProfileRotations field on AuthConfig.cooldowns
src/config/zod-schema.ts — zod validation for new field

Configuration

{
  "auth": {
    "cooldowns": {
      "rateLimitedProfileRotations": 1
    }
  }
}

Set to 0 to escalate immediately on first rate-limit without trying any other profiles. Set higher to allow more profile rotations before fallback.

Fixes #58572

Changed files

CHANGELOG.md (modified, +1/-0)
docs/.generated/config-baseline.json (modified, +17/-0)
docs/.generated/config-baseline.jsonl (modified, +2/-1)
docs/concepts/model-failover.md (modified, +7/-4)
docs/gateway/configuration-reference.md (modified, +2/-0)
scripts/openclaw-npm-release-check.ts (modified, +5/-2)
src/agents/model-fallback.run-embedded.e2e.test.ts (modified, +159/-16)
src/agents/pi-embedded-runner/run.ts (modified, +48/-0)
src/agents/pi-embedded-runner/run/helpers.ts (modified, +5/-0)
src/auto-reply/reply/commands-status.ts (modified, +6/-3)
src/auto-reply/reply/commands-tasks.ts (modified, +8/-3)
src/config/schema.base.generated.ts (modified, +10/-0)
src/config/schema.help.ts (modified, +2/-0)
src/config/schema.labels.ts (modified, +1/-0)
src/config/types.auth.ts (modified, +5/-0)
src/config/zod-schema.ts (modified, +1/-0)
src/cron/service.jobs.test.ts (modified, +31/-1)
src/cron/service/jobs.ts (modified, +24/-4)
src/cron/service/ops.ts (modified, +6/-5)
src/cron/service/timer.ts (modified, +6/-5)
src/tasks/task-registry-import-boundary.test.ts (modified, +1/-1)
src/tasks/task-status-access.ts (added, +10/-0)

Code Example

failoverReason: "overloaded"
model: "claude-sonnet-4-6"
providerErrorType: "overloaded_error"

---

"agents.defaults.fallback.overloadedMaxRetries": 3

RAW_BUFFERClick to expand / collapse

Problem

When an Anthropic model returns overloaded_error (HTTP 529 / Overloaded), OpenClaw currently:

✅ Rotates between auth tokens (profiles) — good
❌ Does NOT fall back to the next model in the fallbacks chain

If claude-sonnet-4-6 is overloaded, and fallbacks include claude-opus-4-6, the gateway retries Sonnet indefinitely across auth tokens but never switches to Opus.

Observed behavior

Gateway logs show repeated:

failoverReason: "overloaded"
model: "claude-sonnet-4-6"
providerErrorType: "overloaded_error"

Every ~10s, never falling back to the next model.

Expected behavior

After N retries of overloaded_error on the same model, fall through to the next model in the fallbacks chain.

Proposed solution

Treat overloaded_error the same as rate_limit for model fallback purposes (not just auth rotation). Or add a config option:

"agents.defaults.fallback.overloadedMaxRetries": 3

Environment

OpenClaw 2026.3.28 (f9b1079)
Provider: Anthropic (OAuth tokens)
Linux x64

extent analysis

TL;DR

Implement a fallback mechanism to switch to the next model in the chain after a specified number of retries when encountering an overloaded_error.

Guidance

Modify the existing fallback logic to treat overloaded_error similarly to rate_limit for model fallback purposes.
Introduce a configuration option, such as "agents.defaults.fallback.overloadedMaxRetries", to specify the maximum number of retries before falling back to the next model.
Update the gateway to track the number of retries for each model and trigger a fallback when the specified threshold is reached.
Verify the fallback behavior by simulating an overloaded_error and checking if the gateway correctly switches to the next model in the chain.

Example

{
  "agents": {
    "defaults": {
      "fallback": {
        "overloadedMaxRetries": 3
      }
    }
  }
}

Notes

The proposed solution assumes that the existing auth token rotation mechanism is working correctly and that the issue is solely related to the model fallback logic. Additional testing may be necessary to ensure that the fallback mechanism works as expected in different scenarios.

Recommendation

Apply workaround by introducing the proposed configuration option and modifying the fallback logic to handle overloaded_error as suggested. This approach allows for a flexible and configurable solution that can be adjusted based on specific requirements and constraints.

Vote matrix · Quick signals

Works

Did the solution work? Tap to confirm.

Easy Fix

Was it a quick fix?

Time Saver

Did it save you time?

Blocking

Was it severely blocking?

Common Issue

Are others likely hitting this too?

Flaky / Intermittent

Is it intermittent?

Verified / Reproducible

Can you reproduce it reliably?

FAQ

Expected behavior

After N retries of overloaded_error on the same model, fall through to the next model in the fallbacks chain.

#indexing error #inference speed #output truncation #response parsing #generation error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Data

Security

Network

Code

UI/UX

Text

System

Multimedia

Protocol

API

Engineering

openclaw - ✅(Solved) Fix Feature request: overloaded_error should trigger model fallback, not just auth token rotation [1 pull requests, 1 participants]

Recommended Tools

GitHub issue graph ai analysis

Error Message

PR fix notes

PR #58707: fix: escalate to model fallback after rate-limit profile rotation cap

Description (problem / solution / changelog)

Problem

Observed behavior

Fix

Changes

Configuration

Changed files

Code Example

Problem

Observed behavior

Expected behavior

Proposed solution

Environment

extent analysis

TL;DR

Guidance

Example

Notes

Recommendation

FAQ

Expected behavior

Still need to ship something?

TRENDING

openclaw - ✅(Solved) Fix Feature request: overloaded_error should trigger model fallback, not just auth token rotation [1 pull requests, 1 participants]

Recommended Tools

GitHub issue graph ai analysis

Error Message

PR fix notes

PR #58707: fix: escalate to model fallback after rate-limit profile rotation cap

Description (problem / solution / changelog)

Problem

Observed behavior

Fix

Changes

Configuration

Changed files

Code Example

Problem

Observed behavior

Expected behavior

Proposed solution

Environment

extent analysis

TL;DR

Guidance

Example

Notes

Recommendation

FAQ

Expected behavior

Still need to ship something?

RELATED_DISCOVERY

TRENDING