Errors

Why a call or session failed, and whether to retry.

Handle errors in code

The SDKs raise a typed error on any non-2xx response, with status_code / statusCode and the parsed body.

Python

from hai_agents import Client
from hai_agents.core import ApiError

client = Client()

try:
    session = client.sessions.create_session(
        agent="h/web-surfer-flash",
        messages=[{"type": "user_message", "message": "Open Hacker News and list the top 3 stories with their URLs."}],
    )
except ApiError as err:
    print(err.status_code, err.body)

Codes	Retry?
408, 429, 5xx	Yes, with backoff, honoring Retry-After. The SDKs retry 408 and 429 on any request, and 5xx on GET, PUT, and DELETE, twice by default (tune with max_retries). Retry the others yourself: resend a POST /sessions with the same Idempotency-Key to avoid a duplicate.
409, 412	After acting on the cause: wait for Retry-After, or re-read the resource.
400, 401, 403, 404, 410, 413, 422	No. The same request fails the same way: fix it.

Session failures

A settled session reports two signals on status, the session object, and changes, so your code can branch without parsing prose.

Outcomes

A session can end completed and still not do what you asked. outcome is the agent’s own assessment, reported with its final answer:

outcome	Meaning	Typical next step
success	Task fully done.	Use the answer.
partial	Some of the task done, not all.	Inspect before trusting.
infeasible	Can’t be done as specified (for example, the item doesn’t exist).	Don’t retry.
blocked	An external obstacle stopped progress: login wall, captcha, missing permissions.	A human connects an account or a vault.

outcome is a self-assessment, not verified ground truth: validate the answer itself for high-stakes flows. It is null when the agent ended without reporting one.

Error codes

When a session ends failed or timed_out, it carries an error_code and an error message matching it:

error_code	Meaning	Retry?
environment_error	The environment failed to provision or crashed.	Yes, as is.
no_answer	The agent ran out of budget (max_steps / max_time_s) or stopped without an answer.	Yes, with a higher budget or a narrower task.
answer_validation	The agent answered, but every attempt failed to match its answer_format.	Maybe. Simplify the schema or loosen required fields.
timeout	On failed: the agent kept going after its max_time_s final-answer request. On timed_out: the session waited 24 hours in the queue.	Yes, with a higher max_time_s or a smaller task, or once a slot is free.
insufficient_credit	The organization used its plan’s included agent usage and has no credit left for the session’s model calls.	Yes, after topping up credit or when the allowance renews.
internal	Unexpected platform error.	Yes, once. If it persists, contact support.

• error_code is null unless the status is failed or timed_out.
• New codes may appear: treat unknown values like internal.
• Branch on error_code, log error.

Python

result = client.run_session(
    agent="h/web-surfer-flash",
    messages="Cancel my Acme Co subscription",
)

if result.status in ("failed", "timed_out"):
    if result.error_code == "environment_error":
        ...  # transient: retry as is
    elif result.error_code in ("no_answer", "timeout"):
        ...  # raise the budget or narrow the task
    else:
        raise RuntimeError(f"Session failed: {result.error} ({result.error_code})")
elif result.outcome == "blocked":
    ...  # needs credentials or a human in the loop
elif result.outcome != "success":
    ...  # "partial", "infeasible", None: inspect before trusting

HTTP status codes

Client error codes

Code	Meaning	Common cause	What to do
400 Bad Request	Malformed request or invalid parameters.	Sending an event to a session that can’t accept it.	Check the body against the endpoint docs.
401 Unauthorized	Missing or invalid API key.	No Authorization header, or expired key.	Check the key and its format.
403 Forbidden	Valid key, not allowed.	Modifying a reserved h/ agent, or a session with an environment kind that isn’t public yet (detail[].type is environment_not_public).	Check that your role allows it.
404 Not Found	Resource missing or not visible to you.	Wrong session ID, or another team’s resource.	Check the ID and your access.
408 Request Timeout	The request timed out before the server processed it.	A slow or stalled connection.	Retry.
409 Conflict	Resource exists, the session’s state forbids the action, or an identical idempotent request is still in flight.	Duplicate agent name, pausing a finished session, a message to a session that is still stopping (detail[].type is session_stopping), or a retry with the same Idempotency-Key before the first finished.	Use a unique name, fetch the existing resource, or retry after Retry-After.
410 Gone	A stored agent revision no longer validates.	Reading or running an old name:N revision stored by an older schema.	Use a newer revision.
412 Precondition Failed	If-Match names a revision that is no longer current.	Another write landed since you read the agent.	Read the ETag header, reapply your change, and retry.
413 Content Too Large	Response page too large.	Listing skills whose files exceed 8 MiB in one page.	Retry with size=1.
422 Unprocessable Entity	Body fails validation.	Missing fields, wrong types.	Read the detail array.
429 Too Many Requests	At the concurrency limit with queueing declined, or the queue is full.	Too many sessions at once.	See Quota errors for which limit was hit.

Quota errors (429)

A session 429 says which limit was hit in detail[].type, and whose slots ran out in detail[].scope:

Quota error (429)

{
  "message": "Concurrent trajectory limit reached (10/10)",
  "detail": [
    { "type": "plan_limit", "message": "Concurrent trajectory limit reached (10/10)", "scope": "user" }
  ]
}

type	scope	Meaning	What to do
plan_limit	user or org	Your plan’s concurrent sessions are all in use.	Leave queue at its default, wait for one of your sessions to finish, or ask for a higher quota.
capacity	platform	The platform is full. Stopping your own sessions doesn’t help.	Retry later.
queue_full	org	Your organization’s queue is full.	Wait for queued sessions to start.

In the local runtime, its session cap answers capacity with scope platform.

Server error codes

Code	Meaning	What to do
502 Bad Gateway	Upstream service error.	Retry after a short pause.
503 Service Unavailable	A dependency is temporarily unavailable, for example billing on session create (detail[].type is billing_unavailable).	Retry with backoff, after Retry-After when present.
504 Gateway Timeout	Request took too long.	Retry.

Error envelope

Every error response carries the same envelope: a message that summarizes the problem, and a detail array with one entry per problem. For 422 validation errors, each detail entry keeps the failing field’s path and reason, and message flattens them into one line:

Validation error (422)

{
  "message": "agent: Field required",
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "agent"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

Requests rejected before they reach the API (for example 401) may carry only a message.

Vault, browser profile and session file endpoints are the exception: apart from 422 validation errors, most of their errors carry a single detail string and no message:

Vault not found (404)

{ "detail": "Vault config not found: 3b8d9c2e-6f1a-4e5b-8c7d-0a9b8c7d6e5f" }