What causes "UCloud Agent Sandbox rate limited, please retry: {exc}" in infiniflow/ragflow?

Retry with exponential backoff and jitter (this error is explicitly retryable).

infiniflow/ragflow · warning · RuntimeError

UCloud Agent Sandbox rate limited, please retry: {exc}

Error message

UCloud Agent Sandbox rate limited, please retry: {exc}

What it means

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.

Source

Thrown at agent/sandbox/providers/ucloud_agent_sandbox.py:128

        language = self._normalize_language(template)
        if language not in {"python", "nodejs"}:
            raise RuntimeError(f"Unsupported language for UCloud Agent Sandbox provider: {template}")

        sdk = _get_ucloud_sandbox_module()
        try:
            sandbox = sdk.Sandbox.create(
                template=self.template,
                timeout=self.sandbox_timeout,
                metadata={"source": "ragflow"},
                secure=True,
                allow_internet_access=self.allow_internet_access,
                **self._api_options(),
            )
        except sdk.AuthenticationException as exc:
            raise SandboxProviderConfigError("UCloud Agent Sandbox authentication failed: check the API key.") from exc
        except sdk.RateLimitException as exc:
            raise RuntimeError(f"UCloud Agent Sandbox rate limited, please retry: {exc}") from exc
        except sdk.TimeoutException as exc:
            raise TimeoutError("Timed out while creating a UCloud Agent Sandbox.") from exc
        except Exception as exc:
            raise RuntimeError(f"Failed to create UCloud Agent Sandbox: {exc}") from exc

        remote_work_dir = posixpath.join(SANDBOX_HOME, f"ragflow-codeexec-{uuid.uuid4().hex}")
        try:
            sandbox.commands.run(
                f"mkdir -p {shlex.quote(posixpath.join(remote_work_dir, 'artifacts'))}",
                timeout=min(self.timeout, 10),
                request_timeout=self.timeout,
            )
        except Exception:
            self._safe_kill(sandbox)
            raise

        instance_id = str(uuid.uuid4())
        self._instances[instance_id] = {"sandbox": sandbox, "remote_work_dir": remote_work_dir, "language": language}

View on GitHub (pinned to 554fb1133a)

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.

Example fix

# before
for task in tasks:
    inst = provider.create_instance("python")  # bursts -> RateLimitException

# after
sem = asyncio.Semaphore(3)
async def run(task):
    async with sem:
        for attempt in range(5):
            try:
                return provider.create_instance("python")
            except RuntimeError as e:
                if "rate limited" not in str(e) or attempt == 4:
                    raise
                await asyncio.sleep(2 ** attempt + random.random())

Defensive patterns

Strategy: retry

Validate before calling

# precheck is impossible (server-side quota); bound concurrency instead
sem = threading.Semaphore(3)  # cap concurrent creates below your UCloud quota
sem.acquire()
try:
    inst = provider.create_instance("python")
finally:
    sem.release()

Type guard

def is_rate_limit_error(exc: RuntimeError) -> bool:
    return "rate limited" in str(exc).lower()

Try / catch

for attempt in range(5):
    try:
        inst = provider.create_instance("python")
        break
    except RuntimeError as e:
        if "rate limited" not in str(e).lower() or attempt == 4:
            raise
        time.sleep((2 ** attempt) + random.random())

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/f4fbd56fff6de04e. Report an issue: GitHub.