Handle API errors

The API uses standard HTTP status codes and a consistent error envelope. When something goes wrong, the response body always has the same shape, so your error-handling code works for every endpoint. This page covers HTTP-level errors: the request itself was rejected or hit a server fault. A session that was accepted but ended failed or timed_out reports why through its error_code; see Read how the run ended.

Error object

Every error response carries the same envelope: a message that summarizes what went wrong, and a detail array with one entry per problem:

Error envelope

{
  "message": "Session not found.",
  "detail": [
    { "type": "not_found", "message": "Session not found." }
  ]
}

For validation errors (422), each detail entry keeps the failing field’s path and reason, and message flattens them into a single line:

Validation error (422)

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

Read message when you just need something to log or display; reach into detail when you need per-field specifics. Requests rejected before they reach the API (for example a missing or invalid key, 401) may carry only a message.

HTTP status codes

Success codes

Code	Meaning	Used by
`200 OK`	Request succeeded.	GET endpoints, updates.
`201 Created`	Resource created.	POST /sessions, POST /agents.
`202 Accepted`	Action accepted, processing asynchronously.	POST /messages, POST /pause, POST /resume.
`204 No Content`	Action succeeded, no response body.	DELETE /sessions, DELETE /agents.

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 request body against the endpoint docs.
`401 Unauthorized`	Missing or invalid API key.	No `Authorization` header, or expired key.	Verify your API key is correct and properly formatted.
`402 Payment Required`	Monthly token budget exhausted.	Creating (or restarting) a session after your organization consumed its plan’s tokens.	The `detail` entry carries `limit`, `used`, and `window_end`; wait for the window to reset or upgrade your plan. See Plans and limits.
`403 Forbidden`	Valid credentials, insufficient permissions.	Trying to modify a reserved `h/` agent.	Check that your role allows this operation.
`404 Not Found`	Resource doesn’t exist or isn’t visible to you.	Wrong session ID, or querying another team’s resource.	Verify the ID and that you have access.
`409 Conflict`	Resource already exists, or an identical idempotent request is still in flight.	Creating an agent with a duplicate name, or retrying a request with the same `Idempotency-Key` before the first one finished.	Use a unique identifier, fetch the existing resource, or wait for the in-flight request to complete.
`422 Unprocessable Entity`	Request body fails validation.	Missing required fields, wrong types.	Check the `detail` array for specific field errors.
`429 Too Many Requests`	Concurrency limit exceeded with queueing declined, or the session queue is full.	Too many sessions running simultaneously.	Leave `queue` at its default to queue instead, wait for running sessions to complete, or request a quota increase. See Plans and limits.

Server error codes

Code	Meaning	What to do
`502 Bad Gateway`	Upstream service error.	Retry after a brief pause.
`503 Service Unavailable`	Temporary capacity issue.	Check the `Retry-After` header and retry.
`504 Gateway Timeout`	Request took too long to process.	Retry the request.

Handling errors with the SDK

The SDKs raise a typed error on any non-2xx response (carrying the status_code / statusCode and parsed body) and return the parsed model on success, so you never narrow a data | error union by hand:

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": "Top 3 stories on Hacker News?"}],
    )
except ApiError as err:
    print(err.status_code, err.body)

import { HaiAgentsClient, HaiAgentsError } from "hai-agents";

const client = new HaiAgentsClient();

try {
  const session = await client.sessions.createSession({
    body: {
      agent: "h/web-surfer-flash",
      messages: [{ type: "user_message", message: "Top 3 stories on Hacker News?" }],
    },
  });
} catch (err) {
  if (err instanceof HaiAgentsError) {
    console.error(err.statusCode, err.body);
  }
}

The SDKs also retry transient errors (408, 429, and all 5xx) with backoff automatically, twice by default. Tune it with max_retries (Python) / maxRetries (TypeScript) on the client, or per call via request options. Calling the API directly? Retry those same codes with backoff, honoring Retry-After when present. Over-quota session creates don’t need retry logic at all: they queue by default and start on their own as slots free up. Do not retry 400, 401, 402, 403, 404, or 422 errors: they signal a problem with the request itself, and the same request will fail the same way. Fix the request instead.

Get started

Concepts

Browser

Desktop

Integrations

Guides

Platform

Error object

HTTP status codes

Success codes

Client error codes

Server error codes

Handling errors with the SDK

​Error object

​HTTP status codes

​Success codes

​Client error codes

​Server error codes

​Handling errors with the SDK

Error object

HTTP status codes

Success codes

Client error codes

Server error codes

Handling errors with the SDK