SDK errors and retries

The Cloud SDKs are unpublished private-preview release candidates.

The Control API returns a canonical error envelope:

{
  "code": "control.EXAMPLE_ERROR",
  "message": "The request could not be completed",
  "correlationId": "corr_...",
  "retryable": false,
  "source": "platform"
}

Field	Meaning
`code`	Stable namespaced identifier such as `control.` or `world.`
`message`	Human-readable explanation
`correlationId`	Identifier to include when requesting support
`retryable`	Whether the server considers the same logical request retryable
`retryAfterMs`	Optional minimum wait before retrying
`operationId`	Optional accepted asynchronous operation to inspect
`issues`	Optional field-level validation failures
`evidence`	Optional session, run, journal, or build context accumulated before failure

TypeScript

Generated requests throw FiredrillError for HTTP or decoding failures and FiredrillTimeoutError when the configured client deadline expires.

import {
  FiredrillError,
  FiredrillTimeoutError,
  FiredrillClient,
} from "@firedrill/cloud";

try {
  await new FiredrillClient({ token }).projectsList();
} catch (error) {
  if (error instanceof FiredrillError) {
    console.error(error.statusCode, error.body);
  } else if (error instanceof FiredrillTimeoutError) {
    console.error("The client stopped waiting; remote state may still change");
  } else {
    throw error;
  }
}

Lifecycle helpers may throw FiredrillLifecycleError, HostedRunRecoveryError, or HostedDrillsRecoveryError. Inspect their pending request or checkpoint and resume it; do not invent a new idempotency key.

Python

Generated requests raise status-specific exceptions such as BadRequestError, UnauthorizedError, ConflictError, or ServiceUnavailableError. Each extends the generated ApiError and carries status_code, headers, and a typed body.

from firedrill_cloud.generated.errors import UnauthorizedError

try:
    client.projects_list()
except UnauthorizedError as error:
    print(error.status_code, error.body.correlation_id, error.body.code)

The helper layer adds FiredrillLifecycleError, HostedRunRecoveryError, and HostedDrillsRecoveryError. Async cancellation remains CancelledError; it is not converted into success or silently retried.

Safe retry rules

Read retryable; do not retry a terminal rejection as if it were transient.
For an unsafe mutation, persist the exact request and Idempotency-Key before dispatch.
If the response is uncertain, repeat that exact request with the same key.
If an operationId is known, poll that operation instead of submitting again.
A client timeout or disconnect means only that the client stopped waiting.
Never treat a queued operation, partial receipt, or interrupted status as completion.

Changing an idempotency key changes the logical request. It is not a retry of an uncertain mutation.

Start here

Local TypeScript SDK

Cloud SDKs

SDK errors and retries

TypeScript

Python

Safe retry rules

​TypeScript

​Python

​Safe retry rules

TypeScript

Python

Safe retry rules