Error handling

An accepted session is not a completed task. After creating a session, poll it or read its message stream until it reaches a terminal state, then inspect isTaskSuccessful, output, lastStepSummary, failureKind and failureStatusCode. isTaskSuccessful says whether the requested result shape was delivered, not whether its content is good enough; null or partial values and the agent's note remain for the caller to judge.

Request errors

Every /v3 endpoint reports failures as a structured JSON envelope, so a caller can branch on a stable field rather than parsing prose. A response that carries no body by specification, such as 204, 304 or any 1xx, stays bodyless.

{
  "code": "SESSION_NOT_IDLE",
  "message": "The session is running, not idle.",
  "resolution": "Wait for the session to become idle before sending a follow-up task.",
  "detail": "Session is running, not idle"
}

Branch and retry on code. It is the stable, machine-readable identifier and does not change wording between releases. message is a human-readable summary, resolution is the action to surface to whoever made the request, and detail is the legacy error text kept for backward compatibility rather than for parsing.

UNEXPECTED_ERROR is also the fallback for any status the instance does not map explicitly, so code is always present even on an error a caller has not seen before.

Never blindly repeat a POST after a network interruption. First list or retrieve sessions to establish whether the instance accepted the original request; otherwise a retry can create duplicate work.

Session failures

When a session ends in error, failureKind tells you whether a retry is sensible. provider_rate_limit, provider_server_error, provider_connection_error and provider_timeout describe failures outside the task itself and are normally worth retrying with back-off. failureStatusCode carries the upstream provider status where one exists.

session_timeout, invalid_output, budget_exceeded and ordinary agent failures need investigation before a repeat. They often point to a task that is too broad, a schema that is too strict, a model choice that does not fit the work, or a maxCostUsd cap that stopped the run. A session interrupted by a server restart may have no failureKind; its lastStepSummary and step feed are the source of truth.

A practical retry policy

Retry temporary provider failures with bounded exponential back-off and a maximum attempt count. Do not retry 422 responses without changing the request. Keep the session id and the final response in your job record, and make processing of a successful output idempotent so a worker restart cannot publish the same result twice. If the result is incomplete, inspect the live view or exported full session before raising limits or resubmitting the task.

Next

The troubleshooting guide covers common host and browser failures. Cost control explains how a spend cap changes a session’s terminal state.