HTTP errors and exceptions - Web Scraping Platform Documentation - Titan Network

Most Task, Analytics, and Billing JSON endpoints return errors in the standard envelope described on 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

{
  "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 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 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 — success envelope and service map
Rate limits — 429 and quotas
Credits and billing — wallet operations and billing scopes
API Reference tab — authoritative parameters and per-operation notes from OpenAPI