nyrn
/
openclaw
mirror of https://github.com/openclaw/openclaw.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: clarify failover 402 handling

This commit is contained in:
Peter Steinberger 2026-04-04 14:46:32 +01:00
parent 73584b1d33
commit 3bc2e47966
No known key found for this signature in database
3 changed files with 16 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/concepts/model-failover.md
View File

@ -155,6 +155,13 @@ State is stored in `auth-profiles.json` under `usageStats`:
Billing/credit failures (for example “insufficient credits” / “credit balance too low”) are treated as failover‑worthy, but they’re usually not transient. Instead of a short cooldown, OpenClaw marks the profile as **disabled** (with a longer backoff) and rotates to the next profile/provider.
Not every HTTP `402` lands here. OpenClaw classifies temporary `402` usage-window
and organization/workspace spend-limit errors as `rate_limit` when the message
looks retryable (for example `weekly usage limit exhausted`, `daily limit
reached, resets tomorrow`, or `organization spending limit exceeded`). Those
stay on the short cooldown/failover path instead of the long billing-disable
path.
State is stored in `auth-profiles.json`:
```json

5
docs/gateway/configuration-reference.md
View File

@ -3129,7 +3129,10 @@ Notes:
}
```
- `billingBackoffHours`: base backoff in hours when a profile fails due to billing/insufficient credits (default: `5`).
- `billingBackoffHours`: base backoff in hours when a profile fails due to true
billing/insufficient-credit errors (default: `5`). Retryable HTTP `402`
usage-window or organization/workspace spend-limit messages stay in the
`rate_limit` path instead.
- `billingBackoffHoursByProvider`: optional per-provider overrides for billing backoff hours.
- `billingMaxHours`: cap in hours for billing backoff exponential growth (default: `24`).
- `authPermanentBackoffMinutes`: base backoff in minutes for high-confidence `auth_permanent` failures (default: `10`).

5
docs/help/faq.md
View File

@ -2367,6 +2367,11 @@ for usage/billing and raise limits as needed.
`ThrottlingException`, `resource exhausted`, and periodic usage-window
limits (`weekly/monthly limit reached`) as failover-worthy rate limits.
Some HTTP `402` responses also stay in that transient bucket. If the
message looks like a retryable usage-window or organization/workspace spend
limit (`daily limit reached, resets tomorrow`, `organization spending limit
exceeded`), OpenClaw treats it as `rate_limit`, not a long billing disable.
Context-overflow errors are different: signatures such as
`request_too_large`, `input exceeds the maximum number of tokens`, or
`input is too long for the model` stay on the compaction/retry path instead