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

# Timeouts and errors

> Set how long a scrape may run with timeout, read the error code Scrape returns, and learn what to do for each. A failed read costs nothing.

`timeout` sets how long Scrape keeps trying to read a page. When a read fails, you get an error with a stable `code` and nothing is charged. This page lists every code Scrape returns and what to do about it.

## Make a request

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). This request reads a page that answers after 10 seconds, with a timeout of 3 seconds.

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/scrape \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://httpbin.org/delay/10",
    "timeout": 3000
  }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/scrape", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://httpbin.org/delay/10",
    timeout: 3000,
  }),
});
const body = await response.json();
if (!response.ok) {
  console.log(body.code, body.retryable, body.retryAfterSeconds);
}
```

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.stophy.dev/v1/scrape",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "url": "https://httpbin.org/delay/10",
        "timeout": 3000,
    },
)
body = response.json()
if not response.ok:
    print(body["code"], body["retryable"], body.get("retryAfterSeconds"))
```

## Read the response

The read ran out of time, so the call failed with HTTP `503`. Nothing was charged.

```json theme={null}
{
  "success": false,
  "error": "The source is not answering right now. Try again shortly.",
  "code": "sourceUnavailable",
  "retryable": true,
  "retryAfterSeconds": 5,
  "requestId": "25f332f5-ed9f-45d7-9441-a02db33651f3"
}
```

Every error has this flat shape. `code` is stable, so branch on it. `error` says what went wrong and what to do. `retryable` says whether sending the same call again can help, and `retryAfterSeconds`, with the `Retry-After` header, says how long to wait. Keep `requestId` for support. See [Errors](https://docs.stophy.dev/api-reference/errors.md).

## Options

| Field | Type | Default | Effect |
| - | - | - | - |
| `timeout` | `number` | `60000` | How long to keep trying, in milliseconds, from 1,000 to 300,000. |

A page that needs a browser needs at least 5 seconds. A slow page can need 10 to 30 seconds the first time. [Waits](https://docs.stophy.dev/scrape/waiting-and-rendering.md) and [actions](https://docs.stophy.dev/scrape/browser-actions.md) use up the same time. Set your own client timeout longer than `timeout`, with a few seconds to spare.

## Error codes

| `code` | Status | What happened | What to do |
| - | - | - | - |
| `invalidRequest` | 400 | A field is wrong, such as `timeout` below 1,000, a file Scrape cannot read, a file larger than 20 MB, or a URL on a private network. The `error` names the field. | Fix the request. Do not retry it as it is. |
| `apiKeyRequired` | 401 | The call needs an API key: an option such as `actions`, `waitFor`, `profile`, `checkPromptInjection`, `redactPII` or `onlyCleanContent`, the formats `audio`, `video` or `json` with a schema or prompt, or a page that only reads with an API key. | Send an API key. See the [Quickstart](https://docs.stophy.dev/quickstart). |
| `unauthorized` | 401 | The API key is not valid or has expired. | Use a valid API key. |
| `insufficientCredits` | 402 | Your balance is lower than the most the call can cost. Nothing was charged. | Add funds, then send it again. |
| `siteNotRead` | 403 | Stophy does not read pages on this site. | Use a [parser](https://docs.stophy.dev/scrape/prebuilt-parsers) for it if one exists, or [search](https://docs.stophy.dev/search/overview) for the topic. |
| `promptInjectionDetected` | 403 | `checkPromptInjection` found instructions aimed at an AI model. See [Safety](https://docs.stophy.dev/scrape/safety.md). | Do not feed the page to a model, or send `checkPromptInjection: false`. |
| `notFound` | 404 | The page has no readable text, the domain has no website, or `lockdown` or `minAge` found no stored copy. | Check the URL. |
| `profileBusy` | 409 | Another call is saving to the same browser profile. | Wait for it, or send `saveChanges: false`. |
| `freeLimit`, `rateLimited` | 429 | You are over the free limit or your rate limit. | Wait `retryAfterSeconds`. See [Rate limits](https://docs.stophy.dev/production/rate-limits.md). |
| `internalError` | 500, 503 | A failure on our side. | Retry in a second. |
| `sourceChanged` | 502 | The answer came back in a shape Stophy could not read. | Retrying will not help yet. Check back later. |
| `busy` | 503 | Stophy is busy. | Wait `retryAfterSeconds`, 5 to 30 seconds. |
| `sourceUnavailable` | 503 | The page did not answer in time, did not finish loading, or could not be reached. | Retry after `retryAfterSeconds`. If it keeps failing, raise `timeout`. |
| `sourceRefused` | 503 | The site is refusing the read right now. | Retry after `retryAfterSeconds`, usually minutes. |
| `sourceTimeout` | 504 | The call took longer than the most Stophy allows. | Retry, or ask for less: fewer formats, fewer actions. |

A page that answers 404 or 410 comes back as a page, with that `metadata.statusCode` and `metadata.error` set to `The page answered with status 404.` It costs nothing. The same holds for each page of a [crawl](https://docs.stophy.dev/crawl/async.md).

## Retry a failed read

Retry only when `retryable` is `true`. Wait `retryAfterSeconds`, or back off 0.5, 1 and 2 seconds. After three tries, stop and log the `requestId`. A retry costs nothing extra, because a failed read is free. [Production troubleshooting](https://docs.stophy.dev/production/troubleshooting.md) has a retry loop.

## Many pages

Scrape reads one URL. A body with `urls` returns `400 invalidRequest` with the message `urls: Send url. To read many pages in one call, use POST /v1/batch/scrape.` To read a list of URLs, send them to a [batch](https://docs.stophy.dev/batches/overview). Each page of a batch or a [crawl](https://docs.stophy.dev/crawl/async.md) succeeds or fails on its own, so one bad page does not fail the rest. The failed pages are listed with their own `code`, `message` and `retryable`.

## Warnings

Some problems do not fail the call. The page still comes back, with a `warning` that says what happened:

* A [browser action](https://docs.stophy.dev/scrape/browser-actions.md) failed, so the page is as it stood before it.
* The text was cut by `maxChars`, and the warning gives the `offset` to read on from.
* `onlyCleanContent` was skipped, or `checkPromptInjection` could not scan the whole page.

## Limits and errors

* `timeout` outside 1,000 to 300,000 returns `400 invalidRequest`.
* The most a single call can run is 5 minutes plus a few seconds.
* A page with more than 8 MB of text, or a file larger than 20 MB, returns `400 invalidRequest`.

## Related

* [Production timeouts](https://docs.stophy.dev/production/timeouts.md) shows how to set client timeouts.
* [Production troubleshooting](https://docs.stophy.dev/production/troubleshooting.md) covers retries and support.
* [Errors](https://docs.stophy.dev/api-reference/errors.md) lists every Stophy error code.
* [Batches](https://docs.stophy.dev/batches/overview) read many URLs in the background.


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