BEEOS CLOUD / DEVELOPER REFERENCE

重试与 HTTP 错误

退避策略、瞬时错误判定与 Cloud HTTP 错误类型。

harness 发起的每个 Cloud 控制面调用都使用同一套重试词汇。选择一个策略，不要自己写 sleep 循环。

abortableSleep

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

等待指定时间；信号一旦中止就立即以其原因拒绝。

function abortableSleep(ms: number, signal?: AbortSignal): Promise<void>

TypeScript · 参数

参数	类型	必填	默认值	说明
`ms`	`number`	是		等待时长，单位毫秒。
`signal`	`AbortSignal`	否		中止该信号会取消等待，并以信号的 reason 拒绝。

返回值 Promise<void>

delayForAttempt

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.retry

返回下一次尝试前的等待毫秒数：初始延迟按之前每次尝试乘以 factor，并以最大延迟封顶。

function delayForAttempt(policy: BackoffPolicy, attempt: number): number

TypeScript · 参数

参数	类型	必填	默认值	说明
`policy`	BackoffPolicy	是		提供初始延迟、倍数和上限的退避策略。
`attempt`	`number`	是		刚失败的尝试序号，从 1 开始。

返回值 number

Python · 参数

参数	类型	必填	默认值	说明
`policy`	BackoffPolicy	是		提供初始延迟、倍数和上限的退避策略。
`attempt`	`int`	是		刚失败的尝试序号，从 1 开始。

返回值 int

isTransientError

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.retry

判断失败是否值得重试：可重试的 CloudHttpError，或拒绝/重置连接、DNS 失败、超时等网络故障。取消永远不算可重试。

function isTransientError(error: unknown): boolean

TypeScript · 参数

参数	类型	必填	默认值	说明
`error`	`unknown`	是		失败操作抛出的值。

返回值 boolean

Python · 参数

参数	类型	必填	默认值	说明
`error`	`BaseException`	是		失败操作抛出的值。

返回值 bool

isTransientStatus

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.retry

判断 HTTP 状态码是否可重试：408、425、429、500、502、503 或 504。

function isTransientStatus(status: number): boolean

TypeScript · 参数

参数	类型	必填	默认值	说明
`status`	`number`	是		响应的 HTTP 状态码。

返回值 boolean

Python · 参数

参数	类型	必填	默认值	说明
`status`	`int`	是		响应的 HTTP 状态码。

返回值 bool

retryWithBackoff

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.retry

重复执行某个操作，直到成功、出现不可重试的错误或策略用尽。

async function retryWithBackoff<T>(operation: (attempt: number) => Promise<T>, options: RetryOptions): Promise<T>

TypeScript · 参数

参数	类型	必填	默认值	说明
`operation`	`(attempt: number) => Promise<T>`	是		要执行的调用，参数是尝试序号（从 1 开始）。
`options`	RetryOptions	是		重试设置：退避策略，以及可选的重试判定、中止信号、重试回调和可替换的 sleep/时钟函数。

返回值 Promise<T>

Python · 参数

参数	类型	必填	默认值	说明
`operation`	`Callable[[int], Awaitable[T]]`	是		要执行的调用，参数是尝试序号（从 1 开始）。
`policy`	BackoffPolicy	是		退避策略：尝试次数、延迟和总耗时预算。
`is_retryable`	`Callable[[BaseException], bool]`	否	`is_transient_error`	判定某个异常是否重试的函数，默认是 `is_transient_error`。
`on_retry`	`Callable[[int, int, BaseException], None] \| None`	否	`None`	每次等待之前调用，参数依次为尝试序号、延迟毫秒数和错误。
`sleep`	`Callable[[float], Awaitable[None]]`	否	`asyncio.sleep`	可替换的 sleep 函数，参数单位为秒，默认是 `asyncio.sleep`，主要用于测试。
`now`	`Callable[[], float]`	否	`time.monotonic`	可替换的单调时钟，返回秒数，默认是 `time.monotonic`。

返回值 T

STARTUP_BACKOFF

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.retry

控制面尚未就绪时使用的策略：两分钟预算内不限次数，等待从 1 秒增长到 15 秒。

const STARTUP_BACKOFF: BackoffPolicy

条目

名称	类型	说明
`maxAttempts`	`number`	不限次数；由时间预算和取消来结束重试。
`initialDelayMs`	`1000`	首次等待 1000 毫秒。
`maxDelayMs`	`15000`	最长等待 15000 毫秒。
`factor`	`2`	每次等待是上一次的 2 倍。
`budgetMs`	`120000`	总预算 120000 毫秒（两分钟）。

TRANSIENT_BACKOFF

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.retry

普通调用遇到网关短暂中断时使用的策略：3 次尝试，依次等待 200 毫秒、500 毫秒。

const TRANSIENT_BACKOFF: BackoffPolicy

条目

名称	类型	说明
`maxAttempts`	`3`	总共 3 次尝试（含第一次）。
`initialDelayMs`	`200`	首次等待 200 毫秒。
`maxDelayMs`	`500`	最长等待 500 毫秒。
`factor`	`2.5`	每次等待是上一次的 2.5 倍，受上限约束。

TRANSIENT_STATUSES

Python beeos_cloud_harness_sdk.retry · 仅 Python

被视为可重试的 HTTP 状态码集合：408、425、429、500、502、503、504。

TRANSIENT_STATUSES = frozenset({408, 425, 429, 500, 502, 503, 504})

CloudHttpError

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.retry

Cloud 返回非 2xx 应答时的错误。body 会被截断，且不含凭据。

class CloudHttpError extends Error
new CloudHttpError(readonly method: string, readonly path: string, status: number, body: string)

TypeScript · 构造

参数	类型	必填	说明
`method`	`string`	是	失败请求的 HTTP 方法。
`path`	`string`	是	失败请求的路径。
`status`	`number`	是	响应的 HTTP 状态码。
`body`	`string`	是	响应体，会被截断到 2048 个字符。

Python · 构造

参数	类型	必填	说明
`method`	`str`	是	失败请求的 HTTP 方法。
`path`	`str`	是	失败请求的路径。
`status`	`int`	是	响应的 HTTP 状态码。
`body`	`str`	是	响应体，会被截断到 2048 个字符。

属性

名称	类型	说明
`readonly status`	`number`	响应的 HTTP 状态码。
`readonly body`	`string`	响应体，最多保留 2048 个字符。
`readonly code?`	`string`	取自 JSON 错误正文的错误码（`error.code` 或 `code`），有则提供。
`readonly transient`	`boolean` / `bool`	状态码属于可重试状态码时为 `true`。
`readonly method`	`string`	失败请求的 HTTP 方法。
`readonly path`	`string`	失败请求的路径。

错误与异常

本模块定义的错误类型。每个方法的说明会写明它在什么情况下抛出哪种错误。

错误	语言	说明
CloudHttpError	TypeScript, Python	Cloud 返回非 2xx 应答时的错误。`body` 会被截断，且不含凭据。

BeeOS Cloud返回文档首页