Skip to main content
Sessions do not always end with completed. When one ends failed or timed_out, the session’s status carries two machine-readable signals so your code can branch without parsing prose:
  • error_code: why the session failed, from a small fixed taxonomy.
  • error: a short, stable, human-readable message matching the code.
Sessions that finish normally carry a third signal, outcome: the agent’s own assessment of how the task went, reported together with its final answer. A session can be completed and still not have done what you asked, so check outcome before trusting the answer. All three appear on status, on the Session object, and on changes.

​
Error codes

error_codeMeaningRetry?
environment_errorThe session’s environment (browser, desktop) failed to provision or crashed.Yes, as is. Nothing about your request was wrong.
no_answerThe agent ran out of budget (max_steps / max_time_s) or stopped without producing an answer.Yes, with a higher budget or a more focused task.
answer_validationThe agent answered, but every attempt failed to match the agent’s answer_format.Maybe. Simplify the schema, or loosen required fields.
timeoutThe session exceeded its maximum allowed time (status is timed_out).Yes, with a higher max_time_s or a smaller task.
internalAn unexpected platform-side error.Yes, once; if it persists, contact support.
error_code is null unless the session’s status is failed or timed_out, and new codes may be added over time, so treat unknown values like internal.
Python
from hai_agents import Client

client = Client()
result = client.run_session(
    agent="h/web-surfer-flash",
    messages="Find the current price of the Framework 13 laptop",
)

if result.status in ("failed", "timed_out"):
    if result.error_code == "environment_error":
        result = client.run_session(...)  # transient: retry as is
    elif result.error_code in ("no_answer", "timeout"):
        ...  # raise the budget or narrow the task before retrying
    else:
        raise RuntimeError(f"Session failed: {result.error} ({result.error_code})")

​
Outcomes

With its final answer, the agent reports how the task concluded:
outcomeMeaning
successThe task was fully accomplished.
partialSome of the task was accomplished, but not all of it.
infeasibleThe task cannot be accomplished as specified (e.g. the requested item does not exist).
blockedAn external obstacle stopped progress: a login wall, captcha, or missing permissions.
The outcome is the agent’s self-assessment, not a verified ground truth. It is a strong routing signal (blocked usually means a human needs to connect an account or a vault; infeasible usually means retrying is pointless), but for high-stakes flows validate the answer itself. outcome is null when the agent ended without reporting one, including all sessions that predate this field.
TypeScript
import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();
const result = await client.runSession({
  agent: "h/web-surfer-flash",
  messages: "Cancel my Acme Co subscription",
});

switch (result.outcome) {
  case "success":
    return result.answer;
  case "blocked":
    // needs credentials or a human in the loop
    return escalate(result);
  case "infeasible":
    return giveUp(result);
  default:
    // "partial", null: inspect before trusting
    return review(result);
}

​
What you will never see

The error message is a stable template derived from error_code, never raw internals: no tracebacks, file paths, or provider error strings. Do not match on the message text; branch on error_code and log the message.