{"record":{"id":"f7b38440256fec86","repo":"shareAI-lab/learn-claude-code","slug":"max-retries-max-retries-exceeded","errorCode":null,"errorMessage":"Max retries ({MAX_RETRIES}) exceeded","messagePattern":"Max retries \\((.+?)\\) exceeded","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"s15_integrated_harness/code.py","lineNumber":2071,"sourceCode":"            if \"ratelimit\" in name or \"429\" in msg:\n                delay = retry_delay(attempt)\n                print(f\"  \\033[33m[429] retry {attempt + 1}/{MAX_RETRIES} \"\n                      f\"after {delay:.1f}s\\033[0m\")\n                time.sleep(delay)\n                continue\n            if \"overloaded\" in name or \"529\" in msg or \"overloaded\" in msg:\n                state.consecutive_529 += 1\n                if state.consecutive_529 >= MAX_CONSECUTIVE_529 and FALLBACK_MODEL:\n                    state.current_model = FALLBACK_MODEL\n                    state.consecutive_529 = 0\n                    print(f\"  \\033[31m[529] switching to {FALLBACK_MODEL}\\033[0m\")\n                delay = retry_delay(attempt)\n                print(f\"  \\033[33m[529] retry {attempt + 1}/{MAX_RETRIES} \"\n                      f\"after {delay:.1f}s\\033[0m\")\n                time.sleep(delay)\n                continue\n            raise\n    raise RuntimeError(f\"Max retries ({MAX_RETRIES}) exceeded\")\n\n\ndef is_prompt_too_long_error(e: Exception) -> bool:\n    msg = str(e).lower()\n    return ((\"prompt\" in msg and \"long\" in msg)\n            or \"context_length_exceeded\" in msg\n            or \"max_context_window\" in msg)\n\n\n# -- Background Tasks --\n\n# Slow tools return a placeholder tool_result immediately. Their real output is\n# later injected as a task_notification, so the main loop can keep moving.\n_bg_counter = 0\nbackground_tasks: dict[str, dict] = {}\nbackground_results: dict[str, str] = {}\nbackground_lock = threading.Lock()\n","sourceCodeStart":2053,"sourceCodeEnd":2089,"githubUrl":"https://github.com/shareAI-lab/learn-claude-code/blob/985456f4adea6f4df8fbad4112245dbd97444eae/s15_integrated_harness/code.py#L2053-L2089","documentation":"The API-call retry loop handles overloaded/529 responses by sleeping with backoff and retrying, up to MAX_RETRIES attempts. If the provider is still returning overload errors after the final attempt, the loop exits and raises this RuntimeError — the caller has exhausted the configured retry budget against a persistently saturated upstream.","triggerScenarios":"Anthropic/API provider returning HTTP 529 or 'overloaded_error' for every attempt in the window; MAX_RETRIES set low while an incident is ongoing; a fallback model also overloaded (switching to FALLBACK_MODEL after MAX_CONSECUTIVE_529 doesn't help if it is saturated too); retry_delay backoff shorter than the incident.","commonSituations":"Provider capacity incidents at peak hours; small MAX_RETRIES/MAX_CONSECUTIVE_529 defaults in stress tests; bursty fan-out workloads from many agents sharing one key.","solutions":["Wait and retry at a coarser cadence (the incident is upstream); space out requests to reduce concurrent load.","Raise MAX_RETRIES and/or the backoff curve (retry_delay) in config so the loop spans the incident.","Configure a healthy FALLBACK_MODEL on a different provider/family so the 529 switch actually lands somewhere available.","If self-hosting the gateway, check its rate limits — sustained 529-like responses can be your own proxy shedding load."],"exampleFix":"// before\nMAX_RETRIES = 3\n\n// after\nMAX_RETRIES = 8  # span typical overload windows; backoff grows per attempt","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    response = call_api_with_retries()\nexcept RuntimeError as e:\n    if \"Max retries\" in str(e):\n        schedule_retry_later(cooldown_minutes=10)  # coarse outer retry\n        return \"API overloaded; queued retry\"\n    raise","preventionTips":["Set MAX_RETRIES and backoff to span realistic overload windows.","Configure a FALLBACK_MODEL on a different provider.","Throttle concurrent agent sessions during peak hours.","Treat this as transient: queue and retry later, don't drop tasks."],"tags":["api","retry","rate-limit","availability","network"],"backgroundTag":null,"analyzedSha":"985456f4adea6f4df8fbad4112245dbd97444eae","analyzedAt":"2026-08-14T22:02:26.028Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}