Handle errors and limits - Tilion

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

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())

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());

# -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.

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 and rate-limit reference for route-specific codes.