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

# Handle errors and limits

> Inspect API errors, distinguish session conflicts, and retry failed requests.

Check the HTTP status before reading a success response. Capture `X-Request-ID` when reporting a failed call.

```python Python theme={"dark"}
import os
import requests

response = requests.get(
    "https://back.tilion.dev/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['TILION_API_KEY']}"}, timeout=30,
)
if not response.ok:
    print("Request ID:", response.headers.get("X-Request-ID"))
    print("Retry after:", response.headers.get("Retry-After"))
    print("Response:", response.text)
    response.raise_for_status()
print(response.json())
```

```javascript Node.js theme={"dark"}
const response = await fetch("https://back.tilion.dev/v1/usage", {
  headers: { Authorization: `Bearer ${process.env.TILION_API_KEY}` },
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  console.error("Request ID:", response.headers.get("X-Request-ID"));
  console.error("Retry after:", response.headers.get("Retry-After"));
  throw new Error(`${response.status}: ${await response.text()}`);
}
console.log(await response.json());
```

```bash curl theme={"dark"}
# -i includes status and response headers.
curl --fail-with-body -i https://back.tilion.dev/v1/usage \
  -H "Authorization: Bearer $TILION_API_KEY"
```

`detail` can be a string, an object, or a list of validation errors. Parse it according to its type.

## Decide whether to retry

| Response | Action |
| - | - |
| `400` or `422` | Correct the request fields. |
| `401` or `403` | Check the key, scopes, or account access. |
| `402` | Check credits, allowances, and spend limits. |
| `409 session_busy` | Wait for the current operation to finish. |
| `409 session_driven_by_client` | Disconnect the main CDP, native Playwright, or VNC client before retrying REST calls. CDP observers can remain connected. |
| `410` | Create a new session. |
| `429` | Respect `Retry-After`. A concurrency-limit error also requires an available session slot. |
| `502` | Retry with backoff. Reuse the creation request's idempotency key if applicable. |

> [!NOTE]
>
> HTTP success does not guarantee browser-task success. Check `content_ok` for fetch, `ok` for actions and agent tasks, and the terminal job status for asynchronous work.

Concurrency counts live sessions across your account. `GET /v1/usage` returns `concurrency_limit` and the applicable rate limits. Close unused sessions before starting more.

See the [error reference](https://docs.tilion.dev/account/errors.md) and [rate-limit reference](https://docs.tilion.dev/account/rate-limits.md) for route-specific codes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.