Errors & handling

Errors use standard HTTP status codes with a consistent JSON body:

{ "error": "invalid_input", "detail": "start_urls is required", "actor": "website-content-crawler" }

Status codes

Code	Meaning	What to do
`400`	Bad/invalid input	Check the actor's input schema (`GET /v1/actors/{name}`).
`401`	Missing/invalid API key	Send a valid `X-API-Key`.
`403`	Key lacks access (tier/feature)	Upgrade or enable the feature.
`404`	Unknown actor or route	Check the actor name.
`422`	Input failed validation	Fix the field named in `detail`.
`429`	Rate limited	Back off; honor the `Retry-After` header.
`500`	Server error	Retry with backoff; if it persists, contact support.
`502/504`	Upstream/source timeout	The target site/API was slow â€” retry.

Handling pattern

r = requests.post(url, headers=headers, json=payload)
if r.status_code == 429:
    time.sleep(int(r.headers.get("Retry-After", 2)))
    r = requests.post(url, headers=headers, json=payload)
r.raise_for_status()
items = r.json()["items"]

A PARTIAL status means some sources failed but you still got usable items â€” always check status.