CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS

Updated October 15, 2026 by Alex Sorokoletov

CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS is a Claude Code environment variable: Bounds how long unattended retry mode (CLAUDE_CODE_RETRY_WATCHDOG) waits for a usage-limit reset. When a 429 response's reset is farther out than this budget, the request ends with an api_request_usage_limit_wait_too_long error instead of sleeping until the reset. Added in v2.1.301 and still present in v2.1.301. It is not in the official reference.

How to set it

For one session, export it in the shell that starts Claude Code:

export CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS=<value>
claude

To apply it to every session, add it to the env object of a settings file:

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS": "<value>"
  }
}

Release notes that mention it

• Claude Code Version Tracker: Undocumented Env Vars, Feature Gates & Models
• claude-code-env-vars-v2-1-301

Related variables

• CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS: Caps the total time unattended retry mode (CLAUDE_CODE_RETRY_WATCHDOG) waits through 429 and 529 responses.
• CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS: Raises the ceiling on the backoff delay when retrying a request that returned a 529 overloaded response.
• CLAUDE_CODE_RETRY_WATCHDOG: Tunes the retry watchdog that detects API calls silently looping without progress.
• BASH_MAX_TIMEOUT_MS
• CLAUDE_CODE_MAX_RETRIES: Maximum API request retries.
• CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS: Sets the base delay, in milliseconds, for the backoff when a request comes back overloaded (HTTP 529).
• CLAUDE_CODE_SIMULATE_PROXY_USAGE: Simulates proxy-based API routing without an actual proxy.
• CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS

Frequently asked questions

All variables, searchable: Claude Code environment variables.