BEEOS CLOUD / DEVELOPER REFERENCE

Retry and HTTP errors

Backoff policies, transient-error classification and the Cloud HTTP error type.

Every Cloud control-plane call a harness makes uses one retry vocabulary. Pick a policy instead of writing your own sleep loop.

abortableSleep

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

Waits for the given time and rejects as soon as the signal is aborted.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`ms`	`number`	yes		Time to wait, in milliseconds.
`signal`	`AbortSignal`	no		Aborting this signal cancels the wait and rejects with the signal's reason.

Returns Promise<void>

delayForAttempt

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

Returns the wait in milliseconds before the next attempt: the initial delay multiplied by the factor for every earlier attempt, capped at the maximum delay.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`policy`	BackoffPolicy	yes		The backoff policy that supplies the initial delay, factor and cap.
`attempt`	`number`	yes		Number of the attempt that just failed, starting at 1.

Returns number

Python · Parameters

Parameter	Type	Required	Default	Description
`policy`	BackoffPolicy	yes		The backoff policy that supplies the initial delay, factor and cap.
`attempt`	`int`	yes		Number of the attempt that just failed, starting at 1.

Returns int

isTransientError

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

Tells whether a failure is worth another attempt: a transient CloudHttpError, or a network failure such as a refused or reset connection, a DNS failure or a timeout. Cancellation is never transient.

function isTransientError(error: unknown): boolean

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`error`	`unknown`	yes		The value thrown by the failed operation.

Returns boolean

Python · Parameters

Parameter	Type	Required	Default	Description
`error`	`BaseException`	yes		The value thrown by the failed operation.

Returns bool

isTransientStatus

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

Tells whether an HTTP status is transient: 408, 425, 429, 500, 502, 503 or 504.

function isTransientStatus(status: number): boolean

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`status`	`number`	yes		HTTP status code of the response.

Returns boolean

Python · Parameters

Parameter	Type	Required	Default	Description
`status`	`int`	yes		HTTP status code of the response.

Returns bool

retryWithBackoff

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

Runs an operation until it succeeds, a non-retryable error occurs, or the policy is exhausted.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`operation`	`(attempt: number) => Promise<T>`	yes		The call to run. It receives the attempt number, starting at 1.
`options`	RetryOptions	yes		Retry settings: the policy, an optional retry predicate, an abort signal, a retry callback and replaceable sleep and clock functions.

Returns Promise<T>

Python · Parameters

Parameter	Type	Required	Default	Description
`operation`	`Callable[[int], Awaitable[T]]`	yes		The call to run. It receives the attempt number, starting at 1.
`policy`	BackoffPolicy	yes		The backoff policy: number of attempts, delays and wall-clock budget.
`is_retryable`	`Callable[[BaseException], bool]`	no	`is_transient_error`	Predicate that decides whether an exception is retried. Defaults to `is_transient_error`.
`on_retry`	`Callable[[int, int, BaseException], None] \| None`	no	`None`	Called before every wait with the attempt number, the delay in milliseconds and the error.
`sleep`	`Callable[[float], Awaitable[None]]`	no	`asyncio.sleep`	Replaceable sleep function that takes seconds. Defaults to `asyncio.sleep`; mainly useful in tests.
`now`	`Callable[[], float]`	no	`time.monotonic`	Replaceable monotonic clock that returns seconds. Defaults to `time.monotonic`.

Returns T

STARTUP_BACKOFF

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

Policy for a control plane that is not ready yet: unlimited attempts within a two-minute budget, waiting 1 s growing to 15 s.

const STARTUP_BACKOFF: BackoffPolicy

Entries

Name	Type	Description
`maxAttempts`	`number`	Unlimited attempts; the budget and cancellation end the retrying.
`initialDelayMs`	`1000`	First wait: 1000 ms.
`maxDelayMs`	`15000`	Longest wait: 15000 ms.
`factor`	`2`	Each wait is twice the previous one.
`budgetMs`	`120000`	Total budget: 120000 ms (two minutes).

TRANSIENT_BACKOFF

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

Policy for short gateway interruptions on ordinary calls: 3 attempts, waiting 200 ms then 500 ms.

const TRANSIENT_BACKOFF: BackoffPolicy

Entries

Name	Type	Description
`maxAttempts`	`3`	Three attempts in total, including the first.
`initialDelayMs`	`200`	First wait: 200 ms.
`maxDelayMs`	`500`	Longest wait: 500 ms.
`factor`	`2.5`	Each wait is 2.5 times the previous one, subject to the cap.

TRANSIENT_STATUSES

Python beeos_cloud_harness_sdk.retry · Python only

The set of HTTP statuses treated as transient: 408, 425, 429, 500, 502, 503 and 504.

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

CloudHttpError

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

Error for any non-2xx answer from Cloud. body is truncated and never contains credentials.

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

TypeScript · Constructor

Parameter	Type	Required	Description
`method`	`string`	yes	HTTP method of the failed request.
`path`	`string`	yes	Request path of the failed request.
`status`	`number`	yes	HTTP status code of the answer.
`body`	`string`	yes	Response body; it is truncated to 2048 characters.

Python · Constructor

Parameter	Type	Required	Description
`method`	`str`	yes	HTTP method of the failed request.
`path`	`str`	yes	Request path of the failed request.
`status`	`int`	yes	HTTP status code of the answer.
`body`	`str`	yes	Response body; it is truncated to 2048 characters.

Properties

Name	Type	Description
`readonly status`	`number`	HTTP status code of the answer.
`readonly body`	`string`	Response body, truncated to 2048 characters.
`readonly code?`	`string`	Error code taken from the JSON error body (`error.code` or `code`), when present.
`readonly transient`	`boolean` / `bool`	`true` when the status is one of the transient statuses.
`readonly method`	`string`	HTTP method of the failed request.
`readonly path`	`string`	Request path of the failed request.

Errors and exceptions

Error types that this module defines. The description of each method says when it raises one.

Errors	Language	Description
CloudHttpError	TypeScript, Python	Error for any non-2xx answer from Cloud. `body` is truncated and never contains credentials.

BeeOS CloudBack to documentation