> ## Documentation Index
> Fetch the complete documentation index at: https://webscraping.titannet.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP errors and exceptions

> How Titan APIs signal failures, where responses diverge from the standard JSON envelope, and what to do next.

Most Task, Analytics, and Billing JSON endpoints return errors in the **standard envelope** described on [API reference overview](/api-reference/overview). This page collects **exceptions** and **practical handling** so you do not have to infer behavior from status codes alone.

## Standard JSON error envelope

```json theme={null}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Human-readable explanation"
  }
}
```

Common `error.code` values include `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `TOO_MANY_REQUESTS`, `NOT_IMPLEMENTED`, and `INTERNAL_SERVER_ERROR`. Your client should branch on **HTTP status** and **`error.code`**, not only on message text.

## 401 vs 403

| HTTP    | Typical `error.code` | Meaning                                                                                                   |
| ------- | -------------------- | --------------------------------------------------------------------------------------------------------- |
| **401** | `UNAUTHORIZED`       | Missing or invalid credentials (no user identity).                                                        |
| **403** | `FORBIDDEN`          | Identity is present but the token lacks [scopes](/get-started/authentication-and-api-keys) for the route. |

Refresh or re-create API keys when scopes change; fix `Authorization: Bearer …` or `X-API-Key` usage when the deployment expects a specific header.

## Rate limiting (429)

Control-plane throttling and **preview quotas** use different bodies and headers. Read [Rate limits](/about-platform/rate-limits) for RPM defaults, **`X-RateLimit-*`** headers, preview **`preview_limit_exceeded`** shapes, and backoff guidance (there is typically **no** `Retry-After` on control-plane 429).

## Feature flags and disabled routes

Some routes return **404** `NOT_FOUND` when a capability is turned off in your environment (for example execution-plan steps when the plan feature is disabled). The OpenAPI **operation description** in the API Reference tab usually states the exact message—search the operation you are calling.

## Responses without the success envelope

| Surface                                                                      | Success                                            | Errors                                                                         |
| ---------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------ |
| **`GET /api/v1/executions/:id/results/export`** and **`…/results/download`** | Raw file bytes (`Content-Disposition: attachment`) | JSON error envelope when the handler rejects the request                       |
| **Media CDN** `GET /media/...?token=…`                                       | Binary stream                                      | `{ "error": "<message>" }` without a `success` field                           |
| **Some billing operations**                                                  | Varies by deployment                               | May use legacy `{ "error": "..." }` shapes; see the Billing API operation text |

## Where to look next

* [API reference overview](/api-reference/overview) — success envelope and service map
* [Rate limits](/about-platform/rate-limits) — 429 and quotas
* [Credits and billing](/about-platform/credits-and-billing) — wallet operations and billing scopes
* **API Reference** tab — authoritative parameters and per-operation notes from OpenAPI