Errors and retries

Status: The source SDK’s minimal durable methods work with the live partner-preview gateway. The package is not published to npm. Turn streaming remains unavailable; exact approval remains pending activation. Cancellation-reconciliation code is deployed, but final-status behavior remains pending a separate live canary.

Two failure lanes

A rejected HTTP request can throw AiPlatformHttpError. Its validated .problem can still be null when a proxy/body is not valid application/problem+json.
An accepted durable task reports execution failure through a terminal run.failed event and RunResource.failure. It does not emit the turn-only request.failed event.

import { AiPlatformHttpError } from "@nexislabs/ai-platform";

try {
  const run = await client.execute(request);
  for await (const event of client.streamRunEvents(run.run_id)) {
    if (event.type === "run.failed") handleRunFailure(event.failure);
  }
} catch (error) {
  if (error instanceof AiPlatformHttpError) {
    handleHttpProblem(error.status, error.problem);
  } else {
    throw error;
  }
}

Use the exact client method available in the source package version you vendor; the package is not yet a public install contract.

HTTP retry rules

problem.retryable is authoritative when a valid problem exists.
Honor Retry-After or retryAfterMs when supplied.
Authentication, authorization, entitlement, validation, and conflict errors require a credential, authority, request, or state change.
Schema/stream parser errors are client/contract bugs, not transient network errors.
Abort errors stop the local request/read; they do not prove a durable task stopped.

Idempotency

Generate one key per logical task and reuse it only for network retries of the same normalized request. If header and body keys are both present, they must be identical. Same key plus same request returns the existing run; same key plus a different request returns 409 conflict. After a dropped submission response, retry the identical request with the same key or read a known run. Never mint a new key merely because the client did not see the first response.

Durable SSE reconnect

Persist an event sequence only after your handler commits it. Reconnect GET /v1/runs/{run_id}/events with that numeric value as Last-Event-ID. The source client rejects mismatched SSE ids, non-increasing sequences, events after a terminal event, and EOF before a terminal event. Only run.completed, run.failed, and run.cancelled are terminal.

Cancellation

cancelRun() requests cooperative cancellation. Its returned run can still be running; cancellation does not undo a committed action. Continue reading the run or SSE until a real terminal projection. Once the reconciliation final-status canary clears, the no-retry progress message is:

The run is reconciling an uncertain execution outcome. Do not retry or resubmit it.

Recovery emits Run reconciliation completed; execution is resuming. If a committing outcome cannot be verified, the terminal failure is:

{
  "code": "run_outcome_unknown",
  "message": "A committing action may have happened, but the final outcome could not be verified. Do not retry automatically.",
  "retryable": false
}

The migration and compatible Workers are deployed, but this final-status behavior remains pending a separate live canary. If received after that gate clears, inspect the external system before submitting replacement work.

Offline turn schemas

The source repository contains candidate turn schemas with request.failed, response.final, tool events, and an approval-resume receipt. They are not served SDK methods: mode: "turn" returns 400 invalid_request, and /v1/chat is not routed. Do not mix them into durable task retry logic. See Errors, Events, and TypeScript SDK.

API reference

Keys & access

Approvals & policy

Studio & workflows

Security

SDK

How-to

Enterprise

Reference

Errors and retries

Two failure lanes

HTTP retry rules

Idempotency

Durable SSE reconnect

Cancellation

Offline turn schemas

​Two failure lanes

​HTTP retry rules

​Idempotency

​Durable SSE reconnect

​Cancellation

​Offline turn schemas

Two failure lanes

HTTP retry rules

Idempotency

Durable SSE reconnect

Cancellation

Offline turn schemas