Fix OpenClaw 429 Rate Limit Errors: Wait, Recover, or Use a Fallback

To recover from an OpenClaw 429 or “rate limit exceeded” error, pause additional requests, find the first rejected attempt, and follow that service's retry guidance. A temporary provider throttle can recover after its minimum wait. An exhausted usage window, empty credit balance, spend cap, or missing access needs its own reset or account action. A 429 during a ClawHub skill download belongs to the registry, so changing your model API key will not fix it.

If the agent is already showing a retry indicator, let its bounded recovery finish instead of repeatedly sending the same task. OpenClaw can continue the existing transcript and preserve completed work. After a terminal failure, inspect changed files, recorded tool results, and external actions before asking it to resume. Restarting the Gateway does not replenish provider quota or clear the general cooldown state stored in SQLite.

The steps below follow official documentation checked on October 5, 2026. They are documented operator procedures; this update did not run OpenClaw commands or make live provider requests.

Find the rejected request before choosing a fix

A final message such as “all models are temporarily rate-limited” describes the exhausted attempt chain. It may follow a primary rate limit, an unavailable backup, and a separate authentication failure. Find the earliest useful error and retain each attempted provider/model, selected profile, HTTP status, error code, and reset or retry information.

On the Gateway host, use a bounded log view rather than assuming every installation writes to one fixed file:

openclaw logs --limit 200 --max-bytes 250000 --plain
openclaw models status

For a named Gateway profile, use its actual name with the root --profile option, as documented for openclaw --profile work logs. For a particular agent, inspect openclaw models status --agent <agentId>, replacing the placeholder with the failing agent's ID. In the affected chat, run:

/model status
/status

The agent CLI explains configured defaults, fallbacks, authentication, and runtime availability. /model status checks the chat's selection; /status can distinguish the selected model from the fallback that answered. Status without --probe is not an inference test. Even a successful --check exit code does not establish that the provider will accept the next request. Models CLI documentation explains these scopes.

If the relevant error falls outside the bounded log view, increase the window only far enough to cover the incident, or use openclaw logs --follow while observing one controlled continuation. The logs reference describes profile-specific rolling files and RPC or journal sources. A disconnected log stream is a separate failure; overlapping lines after reconnection are not proof of additional model calls. Keep private prompts and credentials out of shared diagnostics.

Text such as “error from provider (console)” or “upstream rate limit” does not identify the actual account or endpoint. Record the attempted route before changing its configuration.

How long should you wait for a provider 429?

Wait at least the valid delay supplied by the rejecting provider. There is no universal one-minute or five-minute OpenClaw 429 reset. Requests-per-minute, tokens-per-minute, concurrency, periodic allowances, and spending controls can all produce different recovery conditions.

OpenClaw's current model retry policy allows up to 10 total attempts for rate limits, subject to cancellation and the run deadline. It uses increasing backoff with jitter. Provider hints such as retry-after, retry-after-ms, or “Please try again in…” establish a minimum wait, even when that exceeds the ordinary 30-second backoff cap. This is a bounded continuation policy, not permission to wrap the entire task in an unlimited retry loop.

There are two important exceptions to a simple wait:

• An explicitly exhausted periodic allowance goes directly to eligible auth-profile or model fallback. A Retry-After header alone does not establish that the allowance is exhausted.
• A long server-requested delay can move the run to a configured fallback. The saved retry.provider.maxRetryDelayMs defaults to 60 seconds. When a fallback is configured, a minimum above that cap sends control to an eligible backup. With no fallback, OpenClaw honors the full minimum; a value of 0 disables the cap. This is a controller setting, not a guarantee that every request succeeds within 60 seconds.

OpenClaw also has a separate cap for SDK-internal waits. Its integration can return control from supported provider SDKs when a retry delay exceeds 60 seconds; OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS changes that SDK-only behavior. Do not confuse this with the controller's wait cap or assume that a standalone SDK has the same policy. Native harness retries can occur before OpenClaw receives the failure.

The 90-second consecutive-outage window in the documentation applies to other transient failures, not a universal 429 reset. A completed successful model response clears that outage window without resetting the total retry count. Partial output and tool activity alone do not clear it.

Reduce the requests that are still filling the limit

Pause unnecessary cron jobs, heartbeats, concurrent agents, and caller-side retry loops that use the same constrained account. Let one recovery path own the incident. Resume with one small request after the required delay; increase work gradually only after it succeeds.

For OpenAI API routes, limits can apply at both organization and project levels, and some models share the same rate pool. More keys in the same project or switching between models in a shared pool need not add capacity. Failed requests also count toward per-minute limits. Read the account's limits page and the returned headers for the actual route. OpenAI reset headers can contain durations such as 1s or 6m0s; they are not ClawHub's Unix reset timestamps. OpenAI's rate-limit guide documents these distinctions.

An OpenAI 429 with error.code: slow_down can reflect a rapid traffic increase even below nominal RPM or TPM. Reduce the rate and ramp gradually. A 503 with server_is_overloaded is a separate overload response. A spend alert only notifies you, while an enforced hard spending limit can reject affected requests with a 429.

For Anthropic, 429 rate_limit_error can mean rate pressure, a monthly tier spend cap, or a Claude Code workspace spend limit. A tier spend-cap 429 can lack retry-after and continue until access resumes. Use the selected account's error and billing state instead of repeatedly waiting a guessed interval. Anthropic's error reference explains this branch.

Stop the unchanged retry when the run reaches its deadline or attempt budget, the account requires action, or a controlled request returns the same unresolved condition. Save the pending work and choose the next eligible route or defer it.

“All profiles are in cooldown”: recover stored state correctly

Read Unavailable auth profiles in models status, or auth.unusableProfiles in its JSON output. Look for the reason, recovery action, affected model, and any known expiry. Then match that state to the provider attempt that created it.

Current model failover documentation stores cooldown and disabled state in per-agent SQLite usageStats. Ordinary cooldowns scale from 30 seconds to one minute, then five minutes at the cap. Those are OpenClaw's ordinary failure-state timings; they do not override a provider's longer retry floor or usage-window reset.

Billing failures initially disable a profile for ten minutes, and billing disables block that profile across models. Recharging does not itself clear persisted state. Inline configured keys remain blocked during an active disable window; stored profiles have bounded primary-provider recovery paths. OpenClaw can also attempt a primary near cooldown expiry and evaluate same-provider siblings when a transient failure is model-scoped. These controls let it detect recovery without a universal restart recipe.

Do not delete the auth database or restart repeatedly to erase cooldown. Restarting can clear a separate optional process-local cache used to skip repeated fallback authentication failures, but that cache is not the stored cooldownUntil or disabledUntil, and it is not provider quota. If the first failure was a rejected credential, follow the OpenClaw 401 recovery guide for that agent and session.

Why didn't the configured fallback answer?

First check whether the current selection permits model fallback. A configured default can use its fallback chain. A native agent-specific primary is strict unless that agent's model object includes its own fallbacks. An explicit fallbacks: [] disables model fallback. A model manually chosen in the chat is an exact user selection, so an unrelated configured backup will not silently answer instead.

If you want the chat to use the configured default and its fallback policy, select it deliberately and inspect the result:

/model default
/model status

That choice changes which model policy the chat uses. Keep the exact selection when the task requires one model, runtime, or data boundary; in that case, wait for recovery or explicitly choose an acceptable alternative.

Inspect the configured default chain on the Gateway host:

openclaw models fallbacks list
openclaw models status

These commands do not prove a backup can answer. A useful backup must have a compatible runtime, usable authentication, access to its exact model, sufficient capacity and context, and permission to receive the task's data. Follow the OpenClaw LLM setup guide to connect and separately verify a new route. Adding another key under a shared quota or duplicating the primary model in the fallback list is not evidence of independent capacity.

Current failover can advance on eligible authentication failures, billing disables, rate limits, overload, timeout-shaped failures, and model_not_found. That allows another authorized route to answer; it does not repair the failed credential or billing account. Invalid request formats are usually terminal, while context overflow generally belongs to compaction or its terminal recovery path. A configured backup cannot be assumed to fit the same oversized request. The failover reference documents the exceptions and runtime boundaries.

Read the per-attempt records when the chain fails. Structured model_fallback_decision logs can expose the source model, destination model, original failure reason, and final outcome through fallbackStep* fields. A primary 429 followed by a backup 401 requires two different repairs; a final “all models” summary is insufficient.

When fallback succeeds, it is turn-local. The next turn starts from the selected model again. Check /status to see what actually answered and restore the primary's account or pacing before reopening all background work.

A ClawHub skill download returns “Rate limit exceeded”

Stop repeated install/update attempts and inspect the registry response. ClawHub's read, write, and download buckets are independent of model inference. Anonymous access is limited per IP; a valid Bearer token uses an authenticated user bucket. Missing or invalid tokens fall back to IP enforcement. Shared egress can therefore hit a limit even if you personally made only a few requests. ClawHub troubleshooting recommends signing in where possible and retrying after the reported delay.

Interpret ClawHub headers using its own HTTP API reference:

For example, if a response says Retry-After: 34, wait at least 34 seconds and add a small random delay before the next attempt. Without that header, use the reported reset timing. This is an illustrative calculation, not a fixed ClawHub allowance. Successful sharded responses may omit the remaining-budget header, so an absent value does not mean unlimited capacity.

Current native openclaw skills commands search, install, and update skills; the separate ClawHub CLI supports registry authentication and other registry workflows. If the failing workflow uses that CLI, its documented login checks are:

clawhub login
clawhub whoami

Open the verification URL the CLI prints and authorize its displayed code. Keep tokens private. A successful whoami confirms that CLI's login; it does not establish that a native OpenClaw installer used the same token. Verify the actual download workflow's authentication and response rather than assuming one login repairs every client. The ClawHub overview explains the client roles.

After the delay, retry the required installation once. If it changes to an authentication, scan, moderation, or compatibility error, follow that new error. More waiting or a model fallback cannot repair those conditions. Keep already installed skills and local edits; do not use a blanket force update as a 429 remedy.

Once the download limit has cleared, use our OpenClaw starter skills guide to choose the capabilities your workflow needs before installing more.

Resume unfinished work without replaying completed actions

A failed model request does not undo earlier tools. OpenClaw's documented transient recovery continues the transcript and instructs the model to retain completed work and inspect interrupted actions. If recovery is still active, avoid resubmitting the original task alongside it. Cancellation and a terminal deadline stop further recovery; they do not reverse actions already accepted. Retry policy describes these guarantees and exclusions.

After a terminal error:

1. Check whether any tool or external job is still active. Inspect its actual result before starting another copy.
2. Save the goal, completed changes, checks already run, external identifiers, uncertain actions, and next pending step in a short record you control.
3. Fix the identified limiter, wait for its reset, or select an eligible route. Start with one small continuation rather than replaying the whole assignment.
4. Verify that the reply uses an allowed route and completes the pending step without another 429. Reconcile uncertain external actions before any resend.

A suitable continuation request is: “Read the existing task record and the files already changed. Confirm which checks completed, then run only the pending check. Do not repeat any recorded external action.” Adapt it to the actual work and verify the result.

If large history or tool output is driving token pressure, reduce unnecessary reads and concurrent work. For a genuine overflow or failed summary, use the context and compaction recovery guide, preserving the task record before starting a fresh session. Compaction itself can make a model request and consume the same constrained allowance; repeatedly invoking it during exhausted quota is not a recovery shortcut.

Once the small continuation succeeds, restore background producers gradually. If the same account immediately hits the limit again, its sustainable workload is still below your current demand. Reduce concurrency, shorten unnecessary request content, or arrange suitable capacity before returning to the previous load.

FAQ

Does restarting OpenClaw fix a 429?

It does not refill provider quota or clear the general SQLite cooldown/disabled state. Repair the original cause and allow the applicable window or bounded recovery path. Only a separate optional process-local auth-failure skip cache clears on restart. Current failover documentation distinguishes those states.

Can I rotate API keys to get around the limit?

Another authorized credential helps only if it has usable capacity and is eligible for the selected route. Keys in the same OpenAI organization/project can share limits, and models can share rate pools. Inspect the actual limit before adding credentials. OpenAI rate limits apply to the account and project, not simply the key count.

What if Anthropic says “Extra usage is required for long context requests”?

Treat that exact 429 as a long-context eligibility branch. Check the selected route and credential. Use a standard-window model that fits the task, an eligible credential, or an eligible configured fallback. Remove a legacy context1m setting only when it belongs to the documented older non-GA configuration; do not blindly remove current GA settings or enable paid usage. The specific OpenClaw troubleshooting section describes these alternatives. Preserve the task history before reducing active context.

Why is there another 429 after a fallback succeeded?

A successful fallback answers the current turn; it does not permanently replace the selected primary. The next turn can return to the still-limited route. Check /status, the current selection, and the primary account's reset or capacity before resuming the full workload. Model failover explains this turn-local behavior.