{"record":{"id":"f4fbd56fff6de04e","repo":"infiniflow/ragflow","slug":"ucloud-agent-sandbox-rate-limited-please-retry","errorCode":null,"errorMessage":"UCloud Agent Sandbox rate limited, please retry: {exc}","messagePattern":"UCloud Agent Sandbox rate limited, please retry: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"warning","filePath":"agent/sandbox/providers/ucloud_agent_sandbox.py","lineNumber":128,"sourceCode":"\n        language = self._normalize_language(template)\n        if language not in {\"python\", \"nodejs\"}:\n            raise RuntimeError(f\"Unsupported language for UCloud Agent Sandbox provider: {template}\")\n\n        sdk = _get_ucloud_sandbox_module()\n        try:\n            sandbox = sdk.Sandbox.create(\n                template=self.template,\n                timeout=self.sandbox_timeout,\n                metadata={\"source\": \"ragflow\"},\n                secure=True,\n                allow_internet_access=self.allow_internet_access,\n                **self._api_options(),\n            )\n        except sdk.AuthenticationException as exc:\n            raise SandboxProviderConfigError(\"UCloud Agent Sandbox authentication failed: check the API key.\") from exc\n        except sdk.RateLimitException as exc:\n            raise RuntimeError(f\"UCloud Agent Sandbox rate limited, please retry: {exc}\") from exc\n        except sdk.TimeoutException as exc:\n            raise TimeoutError(\"Timed out while creating a UCloud Agent Sandbox.\") from exc\n        except Exception as exc:\n            raise RuntimeError(f\"Failed to create UCloud Agent Sandbox: {exc}\") from exc\n\n        remote_work_dir = posixpath.join(SANDBOX_HOME, f\"ragflow-codeexec-{uuid.uuid4().hex}\")\n        try:\n            sandbox.commands.run(\n                f\"mkdir -p {shlex.quote(posixpath.join(remote_work_dir, 'artifacts'))}\",\n                timeout=min(self.timeout, 10),\n                request_timeout=self.timeout,\n            )\n        except Exception:\n            self._safe_kill(sandbox)\n            raise\n\n        instance_id = str(uuid.uuid4())\n        self._instances[instance_id] = {\"sandbox\": sandbox, \"remote_work_dir\": remote_work_dir, \"language\": language}","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/agent/sandbox/providers/ucloud_agent_sandbox.py#L110-L146","documentation":"Raised when `sdk.Sandbox.create(...)` throws `sdk.RateLimitException`: the UCloud API refused sandbox creation because the account/project exceeded its creation-rate or concurrency quota. The message embeds the SDK's underlying exception text, and the provider deliberately suggests retry since the condition is transient.","triggerScenarios":"Bursty create_instance() calls — e.g. many agent sessions starting code-execution components at once, or a retry storm after a batch failure — exceeding the UCloud sandbox creation quota.","commonSituations":"Load tests or parallel canvas runs spinning up dozens of sandboxes; a shared UCloud account where another team consumes the quota; tight agent loops that recreate a sandbox per tool call instead of reusing instances.","solutions":["Retry with exponential backoff and jitter (this error is explicitly retryable).","Reuse sandbox instances across executions (create once, run many commands) instead of creating per call.","Throttle concurrency of create_instance at the application layer (semaphore/queue).","Raise the quota with the UCloud account owner if sustained traffic legitimately needs it."],"exampleFix":"# before\nfor task in tasks:\n    inst = provider.create_instance(\"python\")  # bursts -> RateLimitException\n\n# after\nsem = asyncio.Semaphore(3)\nasync def run(task):\n    async with sem:\n        for attempt in range(5):\n            try:\n                return provider.create_instance(\"python\")\n            except RuntimeError as e:\n                if \"rate limited\" not in str(e) or attempt == 4:\n                    raise\n                await asyncio.sleep(2 ** attempt + random.random())","handlingStrategy":"retry","validationCode":"# precheck is impossible (server-side quota); bound concurrency instead\nsem = threading.Semaphore(3)  # cap concurrent creates below your UCloud quota\nsem.acquire()\ntry:\n    inst = provider.create_instance(\"python\")\nfinally:\n    sem.release()","typeGuard":"def is_rate_limit_error(exc: RuntimeError) -> bool:\n    return \"rate limited\" in str(exc).lower()","tryCatchPattern":"for attempt in range(5):\n    try:\n        inst = provider.create_instance(\"python\")\n        break\n    except RuntimeError as e:\n        if \"rate limited\" not in str(e).lower() or attempt == 4:\n            raise\n        time.sleep((2 ** attempt) + random.random())","preventionTips":["Reuse one sandbox instance across many execute() calls instead of creating per request.","Cap concurrent create_instance calls with a semaphore sized under your UCloud quota.","Retry only the rate-limited case (match 'rate limited' in the message); retrying auth or config errors just amplifies load."],"tags":["rate-limit","retry","ucloud","sandbox","throttling"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}