> ## Documentation Index > Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > H Platform has four products: the Agents API (managed computer-use agents, base URL https://agp.eu.hcompany.ai/api/v2 or https://agp.hcompany.ai/api/v2 for the US), the Models API (OpenAI-compatible Holo vision-language models at https://api.hcompany.ai/v1), HoloDesktop CLI (Holo on the user's own desktop), and HoloTab (a free no-code Chrome extension that runs Holo in the user's browser, with recordable routines and schedules). > Authenticate with a bearer API key from the HAI_API_KEY environment variable. SDKs: `pip install hai-agents` (Python, `from hai_agents import Client`) and `npm install hai-agents` (TypeScript, `import { HaiAgentsClient } from "hai-agents"`). CLI: `hai`. > Agents do work in a browser or on a desktop; describe the task as an imperative instruction. To run a task quickly, prefer the pre-built agent `h/web-surfer-flash`. Read results from the session's `latest_answer` after it reaches a terminal status. > Sessions are the unit of work; wait for a terminal status (completed, failed, timed_out, interrupted) before reading the answer. Use webhooks or the `changes` long-poll endpoint to follow progress. # Handle API errors > Agents API error envelope, HTTP status codes from 400 to 504 with causes and fixes, and how the SDKs raise and retry 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](/agents-api/observe-and-steer#read-how-the-run-ended). ## Error object Every error response carries the same [envelope](/agents-api/api-reference#errors): a `message` that summarizes what went wrong, and a `detail` array with one entry per problem. For validation errors (422), each `detail` entry keeps the failing field's path and reason, and `message` flattens them into a single line: ```json Validation error (422) theme={"system"} { "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](/agents-api/plans-and-limits#token-usage). | | `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`](/agents-api/sessions/create#header-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](/agents-api/observe-and-steer#queued-sessions) 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](/agents-api/plans-and-limits#concurrent-sessions). | ### 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: ```python Python theme={"system"} 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) ``` ```typescript TypeScript theme={"system"} 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: "Open Hacker News and list the top 3 stories with their URLs." }], }, }); } 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`](/agents-api/sdks#client-configuration). 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](/agents-api/observe-and-steer#queued-sessions) 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.