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

# Limits and errors

> Cancel a batch, know how many batches run at once and how many wait, handle pages that fail, retry them in a new batch, and read every error a batch returns.

A batch can fail in three places: the call that starts it, a page inside it, and the batch as a whole. This page covers each, and how to stop a batch you no longer need.

## Cancel a batch

`DELETE /v1/batch/scrape/{id}` stops a batch from reading more pages. It answers with `status` `cancelled` at once, and the pages already read are kept.

```bash cURL theme={null}
BATCH_ID="<the id your batch returned>"
curl -X DELETE https://api.stophy.dev/v1/batch/scrape/$BATCH_ID \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

```typescript TypeScript theme={null}
const id = "<the id your batch returned>";
const response = await fetch(`https://api.stophy.dev/v1/batch/scrape/${id}`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}` },
});
console.log(await response.json());
```

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

import requests

batch_id = "<the id your batch returned>"
response = requests.delete(
    f"https://api.stophy.dev/v1/batch/scrape/{batch_id}",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
)
print(response.json())
```

```json theme={null}
{
  "success": true,
  "status": "cancelled",
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "9bb054fc-4ddd-4648-a48f-336b848b1dc0"
}
```

This real batch had 3 pages and was cancelled right after it started. Reading it showed `status` `cancelled`, `total` 3, `completed` 0 and `costUsd` 0. no page was read, so nothing was charged. A batch cancelled later is charged for the pages it finished. Reading the batch then gives its final counts, and `data` holds the pages read.

Cancelling a batch that already ended returns `409 jobFinished`.

```json theme={null}
{
  "success": false,
  "error": "This batch scrape already finished, so there is nothing to cancel. Read its pages with GET /v1/batch/scrape/job_FcxIcgRhtA3DhBn2UjZEFA.",
  "code": "jobFinished",
  "retryable": false,
  "requestId": "c82a2d11-028d-4bef-945d-a7e0dd6e4110"
}
```

To remove a finished batch's pages, see [Delete the results](https://docs.stophy.dev/batches/results.md#delete-the-results). A batch also deletes itself 24 hours after it starts.

## Jobs at once

Batches share three limits with crawls, extracts and agent runs. They depend on your tier, which `GET /v1/limits` returns.

| Limit | `free` | `paid` |
| - | - | - |
| Jobs running at once | 1 | 10 |
| Jobs waiting to start | 5 | 20 |
| Job starts a minute | 10 | 100 |
| Reads a minute: status, results, errors, list | 1,500 | 1,500 |

A batch that starts while your running jobs are at the limit waits. Its answer has `status` `scraping` and a `queuePosition`, and it starts when a place frees up. A batch over the waiting limit returns `429 rateLimited`: `Too many jobs: you already have 6 jobs waiting or running. Send the call again after the number of seconds in retryAfterSeconds.` On the `free` tier that is 1 running and 5 waiting. `retryAfterSeconds` is 30. See [Rate limits](https://docs.stophy.dev/production/rate-limits.md).

A batch holds 1 to 10,000 URLs, and is kept for 24 hours. Pages are read at most 4 at once whatever `maxConcurrency` you send. Read the results as pages finish: a status read already shows the pages that are done.

## Pages that fail

A failed page never makes the call fail. The batch goes on, the page is listed in `errors` with a `code`, and a failed page costs nothing.

```json theme={null}
{
  "url": "https://this-domain-does-not-exist-stophy.com",
  "code": "notFound",
  "message": "That address has no website behind it. Check the spelling of the domain, then try again.",
  "retryable": false,
  "at": "2026-11-17T18:13:12.314Z"
}
```

| `code` | Retry | What happened |
| - | - | - |
| `notFound` | No | The address has no website behind it. A page that answers `404` or `410` is not an error: see [Batches](https://docs.stophy.dev/batches/overview#read-the-response). |
| `siteNotRead` | No | Stophy does not read this site as a page. Use a [pre-built parser](https://docs.stophy.dev/scrape/prebuilt-parsers). |
| `promptInjectionDetected` | No | `checkPromptInjection` found text written to instruct an AI assistant. |
| `sourceUnavailable` | Yes | The site is not answering right now. |
| `sourceRefused` | Yes | The site is refusing requests right now. |
| `sourceTimeout` | Yes | The site took too long. Raise `timeout`. |
| `sourceChanged` | No | The site answered in a shape Stophy could not read. |
| `internalError` | Yes | A fault on Stophy's side. |

Every code is in [API errors](https://docs.stophy.dev/api-reference/errors.md). Read a batch's errors with `GET /v1/batch/scrape/{id}/errors` or in the `errors` of a status read. See [Results](https://docs.stophy.dev/batches/results.md#read-the-errors).

A batch ends `failed` when the batch itself stops, not when some pages fail. It says why in `error`, with one of these messages.

* `Your balance ran out. The pages already read are kept. Add funds, then start a new job for the pages left.`
* `No page could be read. See errors for the reason on each page.`
* `We could not finish this job. The pages already read are kept. Start a new job for the pages left.`

## Retry the failed pages

Collect the `url` of every retryable error, then submit them as a new batch.

```bash cURL theme={null}
BATCH_ID="<the id your batch returned>"
URLS=$(curl -s https://api.stophy.dev/v1/batch/scrape/$BATCH_ID/errors \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  | jq -c '[.errors[] | select(.retryable) | .url]')

if [ "$URLS" != "[]" ]; then
  curl -X POST https://api.stophy.dev/v1/batch/scrape \
    -H "Authorization: Bearer $STOPHY_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"urls\": $URLS, \"formats\": [\"markdown\"]}"
fi
```

```typescript TypeScript theme={null}
const id = "<the id your batch returned>";
const headers = {
  Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
  "Content-Type": "application/json",
};
const errors = await fetch(`https://api.stophy.dev/v1/batch/scrape/${id}/errors`, {
  headers,
}).then((response) => response.json());

const urls = errors.errors
  .filter((error: { retryable: boolean }) => error.retryable)
  .map((error: { url: string }) => error.url);

if (urls.length > 0) {
  const retry = await fetch("https://api.stophy.dev/v1/batch/scrape", {
    method: "POST",
    headers,
    body: JSON.stringify({ urls, formats: ["markdown"] }),
  });
  console.log((await retry.json()).id);
}
```

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

import requests

batch_id = "<the id your batch returned>"
headers = {"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}
errors = requests.get(
    f"https://api.stophy.dev/v1/batch/scrape/{batch_id}/errors", headers=headers
).json()["errors"]

urls = [error["url"] for error in errors if error["retryable"]]
if urls:
    retry = requests.post(
        "https://api.stophy.dev/v1/batch/scrape",
        headers=headers,
        json={"urls": urls, "formats": ["markdown"]},
    )
    print(retry.json()["id"])
```

Send the same `formats` and options as the first batch. When the first batch is still running, add the URLs to it instead with `appendToId`. See [Submit](https://docs.stophy.dev/batches/submit.md#add-urls-to-a-running-batch). Wait a few seconds before you retry `sourceUnavailable` and `sourceRefused`, and do not retry a code marked No.

## Errors from the calls

| Status | `code` | Cause | What to do |
| - | - | - | - |
| 400 | `invalidRequest` | A field is wrong. The error names it: no usable URL, more than 10,000, a bad `webhook`, or results deleted while the batch runs. | Fix the request. |
| 401 | `apiKeyRequired`, `unauthorized` | No API key, or an API key that is not valid. | Send a valid API key. |
| 402 | `insufficientCredits` | `appendToId` with a balance that cannot cover the new pages. | Add funds. |
| 404 | `notFound` | No batch with that id, or it is older than 24 hours. | Check the id. |
| 409 | `jobFinished` | Cancel, or `appendToId`, on a batch that already ended. | Read it, or start a new batch. |
| 429 | `rateLimited` | Too many jobs, or too many calls this minute. | Wait `retryAfterSeconds`, then send it again. |
| 503 | `busy`, `internalError` | Stophy is busy, or a fault on its side. | Wait and retry. A retry with the same `Idempotency-Key` is safe. |

Failed calls cost nothing. [Troubleshooting](https://docs.stophy.dev/production/troubleshooting.md) has a retry loop.

## Related

* [Batches](https://docs.stophy.dev/batches/overview) explains the statuses and the price.
* [Submit a batch](https://docs.stophy.dev/batches/submit.md) covers webhooks, `appendToId` and `Idempotency-Key`.
* [Results](https://docs.stophy.dev/batches/results.md) reads the pages and deletes them.
* [Rate limits](https://docs.stophy.dev/production/rate-limits.md) lists every limit by tier.
* [Cancel reference](https://docs.stophy.dev/api-reference/endpoint/batch-scrape-cancel.md) lists every field.


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