Errors and retries

The TypeScript client exposes the status as AgentAPIError.status. Python raises AgentRunError for HTTP failures with the status in AgentRunError.status.

Neither SDK automatically retries requests. A request can reach the server even if its response never reaches your application.

• For reads, inspect the error and retry according to your application's policy.
• For an existing run, continue reading the same run ID.
• For runs, batches, loops, and campaigns, reuse a stable idempotencyKey (TypeScript) or idempotency_key (Python) for the same logical submission.
• For agent creation without a returned ID, recover the existing agent or build before creating another one.
• Both clients expose run history and cancellation. Inspect saved IDs before resubmitting ambiguous work.

Never treat an expired local deadline as proof that remote work was cancelled.

TypeScript's client timeoutMs applies to each request. Its wait methods accept a separate total timeoutMs. Python wait methods use timeout and interval in seconds. TypeScript defaults to 20 minutes for builds and 10 minutes for single runs. Python defaults to 20 minutes for both.

import { AgentAPIError } from '@parcha/agentrun';
try {
  await client.getRun(savedRunId);
} catch (error) {
  if (error instanceof AgentAPIError) console.error(error.status, error.message);
  else throw error;
}

from agentrun import AgentRunError
try:
    client.get_run(saved_run_id)
except AgentRunError as error:
    print(error.status, str(error))

Local wait timeouts, validation errors, and network errors are separate from HTTP errors. Python raises TimeoutError for polling deadlines and ValueError for invalid configuration. TypeScript build failures expose AgentBuildError.build. Preserve build and resource IDs in application storage before waiting.