# CLAUDE_CODE_MAX_RETRIES

> It sets how many times a failed request is tried again.

**Field:** Artificial Intelligence  
**Category:** Claude Code  
**Also known as:** CLAUDE_CODE_MAX_RETRIES environment variable

## Think of it like

It is like how many times you knock on a door. Then you give up and leave.

## Definition

CLAUDE_CODE_MAX_RETRIES sets how many times Claude Code tries a failed API request again. The default is 10. It can stop sooner when the API says it is overloaded. If you set a fallback model, Claude Code moves to that model in place of showing the error.

## Example

Jack's CI should fail fast, not wait through ten retries. He sets 3, and a broken run ends quickly.

## Example code

```bash
export CLAUDE_CODE_MAX_RETRIES=3
claude -p "Run the checks"
```

Give up sooner in a script.

## Why it matters

Retries ride out short outages, but too many can make a script hang for a long time.

## Common mistake

Raising it to wait through a long outage. There is a separate watchdog variable built for that.

## Three principles

- **Default 10.** Tries again.
- **Stops sooner.** When overloaded.
- **Fallback model.** Switches instead.

## Related terms

- [API_TIMEOUT_MS](https://learn.benibix.com/term/ai/api-timeout-ms-variable)
- [--fallback-model Flag](https://learn.benibix.com/term/ai/fallback-model-flag)
- [Model Fallback](https://learn.benibix.com/term/development/model-fallback)

---

Source: https://learn.benibix.com/term/ai/claude-code-max-retries-variable
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-16
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
