Limits and reliability

Blazing Agents enforces product bounds and durable execution controls, while the tenant's application remains responsible for safe retries and external side effects. Use these contracts to distinguish a platform guarantee from work your integration must reconcile.

Product limits and pagination

Resource counts, text and upload sizes, schedule intervals, usage windows, and page sizes are enforced by public schemas, services, and storage constraints. Use the canonical service-limits table for current values instead of embedding them in application logic.

Unbounded lists use opaque keyset cursors. Pass a returned nextCursor back to the same operation with the same filters; do not decode it or reuse it across collections. Transcript polling also supports a forward after cursor. See pagination and filtering for operation-specific behavior.

Failure and retry model

Validation failures are caller-fixable and should not be retried unchanged. unauthorized requires a valid replacement credential, not_found requires rechecking Tenant scope and lifecycle, and quota_exceeded should wait for a quota or window change. Retry provider_error only after identifying a transient cause, and retry provider or internal failures only when the operation is safe to repeat.

Before a streaming response begins, REST failures use the normal typed error envelope. After a completion or object stream begins, transport or decoding failures surface as SDK stream_error; partial output may already have been observed. A local fetch failure before an HTTP exchange surfaces as network_error. Chat streams carry native AI SDK error chunks after streaming starts.

Never infer retry safety from an error code alone. Read operations are generally repeatable, while creates and external Tool calls can have effects even when their response is lost. Use a documented idempotency field where one exists.

Submit an idempotent Task run

Use one stable key for all retries of the same logical Task submission:

import { BlazingAgents } from "@blazing-agents/sdk";

const apiKey = process.env.BLAZING_AGENTS_API_KEY;
if (!apiKey) throw new Error("BLAZING_AGENTS_API_KEY is required");

const client = new BlazingAgents({ apiKey });
const taskId = "tk_0123456789abcdef";
const idempotencyKey = "daily-report:2026-07-20";

const first = await client.tasks.createRun(taskId, { idempotencyKey });
const replay = await client.tasks.createRun(taskId, { idempotencyKey });

console.log(first.runId === replay.runId);

The expression prints true: the key deterministically selects one Task run identity, and a retry returns and re-enqueues that existing run rather than creating a duplicate. A Task can have only one active run, so choose a key per logical submission rather than reusing one for different work.

Cancellation and deadlines

Task cancellation records intent and is cooperative. The worker observes it at a cancellation boundary and aborts the live Turn; callers should poll until the Task run reaches a terminal status. A worker deadline also aborts the Turn and records a failed outcome.

For a Sandbox-backed Turn, cancellation or deadline stops new dispatch but does not claim that an already accepted native operation has stopped immediately. Admission remains held through quiescing until AgentOS confirms sleep, then DBOS releases the Sandbox and global-capacity slots. Completed filesystem changes or remote Tool effects may remain.

Durable recovery guarantees

DBOS durably records Task workflow progress, Sandbox admission, and release. Task Session events are committed incrementally behind the active-run fence. A product-side Turn claim prevents recovery from rerunning model, Tool, filesystem, Artifact, Session, or usage effects after an unfinished attempt: a recorded completed outcome is reused, while an unfinished claim becomes an interrupted failure.

These controls provide at-most-once Task Turn execution, not exactly-once external effects. Product-database and DBOS-system-database writes are not atomic; reconciliation repairs missed enqueue and scheduling work. Integrations must still reconcile ambiguous remote effects and use compensating actions where needed.

Production considerations

Derive idempotency keys from stable business identities and persist them before submission.
Apply bounded retry counts, exponential backoff, jitter, and an overall deadline appropriate to the operation.
Poll Task runs until a terminal blocked, succeeded, failed, or canceled status, using forward transcript cursors when progress is needed.
Record request IDs, Task and run IDs, error codes, and lifecycle timestamps without logging credentials.
Alert when a Task run remains queued or running beyond the application's deadline, or does not reach a terminal state after cancellation.
Reconcile or compensate for external Tool and filesystem effects after cancellation, timeout, or an ambiguous response.

See Usage and quotas and Tasks and schedules for their complete lifecycle semantics.