Timeouts, limits, and errors

Scrape returns each output independently. Inspect its success even after HTTP 200. isPartial signals failed or incomplete outputs when at least one requested output succeeds; it is absent when all requested outputs fail.

Set a deadline

Send this body to POST /web/scrape. See the Quickstart for authentication and SDK setup.

{
  "url": "https://example.com",
  "formats": {
    "markdown": true,
    "screenshot": true
  },
  "timeoutOpts": {
    "milliseconds": 30000,
    "behavior": "return-partial"
  }
}

The default is 60,000 ms with behavior: "fail". Deadlines range from 1 to 300,000 ms; return-partial requires at least 5,000 ms. Keep your client timeout longer than the API deadline. fail returns 408 if the overall deadline is reached. Individual outputs can fail earlier while the request returns 200. return-partial permits the current page state and available outputs; check the outputs even if none succeeded. Neither behavior guarantees that all dynamic content finished rendering. Fixed action waits and numeric waitFor must fit before the deadline, with a response reserve of up to 5,000 ms (at most one quarter of the timeout).

Size limits

Output	Limit
Original bytes	20 MiB decoded.
Screenshot	20 MiB and 40 megapixels.
Combined response	60 MiB.

An oversized output fails with data: null. If the combined response is too large, the largest outputs are omitted until it fits.

Error handling

Response	Check or action
`200`, one or more failed outputs	Target access, unsupported content, actions, selectors, and output size. Successful outputs remain usable.
`400`	Correct invalid fields, incompatible options, headers, or waits that exceed the deadline.
`401`	Check the API key, its status, and the organization’s balance.
`403`	Check permissions, paid-plan actions, ZDR entitlement, or domain restrictions.
`408`	Shorten the work or increase the deadline.
`429`	Wait for `Retry-After`; see rate limits.
`5xx`	Retry transient failures with bounded backoff.

Keep request_id and error_code for troubleshooting. A screenshot failure, unfinished image enrichment, or failed product fallback can set isPartial without discarding other outputs.

Get started

Web data

Company and people data

Automation

Account and billing

Production

Timeouts, limits, and errors

Set a deadline

Size limits

Error handling

​Set a deadline

​Size limits

​Error handling

Set a deadline

Size limits

Error handling