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

# Troubleshooting

> Read the Stophy error code, retry only rate limits and outages, wait for Retry-After and back off. Every code, its status and what to do, with a retry loop.

Every error has the same flat shape. Save the HTTP status, the `code`, the `requestId` and a copy of your input, and compare your request with the endpoint's [API reference](https://docs.stophy.dev/api-reference/introduction.md) before you retry. A failed call costs nothing, so a retry costs nothing extra.

```json theme={null}
{
  "success": false,
  "error": "Unknown field `colour`. Fields: formats, onlyMainContent, onlyCleanContent, includeTags, excludeTags, maxAge, …",
  "code": "invalidRequest",
  "retryable": false,
  "requestId": "ab4ba002-3e3f-47cf-8f43-9c63de1b9f70"
}
```

This is a real answer with its field list cut. `error` says what went wrong and what to do next. `retryable` is `true` when trying again can help. `retryAfterSeconds`, when present, is also the `Retry-After` header. The `X-Request-ID` header names the request. Include it when you contact support.

## Start with the status

| Status | What to check |
| - | - |
| `200` with less than you expected | A `warning` in the answer, `isTruncated`, a filter that matched nothing, or a page that has no content. See [Timeouts and errors](https://docs.stophy.dev/scrape/timeouts-and-errors.md). |
| `400` | A field the endpoint does not take, or a value it does not accept. `error` names the field. |
| `401` | No API key, a wrong key, an expired key, or a field that needs an API key. See [API keys](https://docs.stophy.dev/account/api-keys.md). |
| `402` | Your balance is too low for the call. Nothing was charged. See [Pricing](https://docs.stophy.dev/account/pricing.md). |
| `403` | The site is read through a parser, the page was refused, or the call needs the dashboard. |
| `404` | The path, the id or the page does not exist, or an id has expired. |
| `405` | The path takes another method. The `Allow` header names it. |
| `409` | The job already ended, the profile is busy, or a check is already running. |
| `413`, `415` | The body is too large, or it is not JSON. |
| `429` | A rate limit. See [Rate limits](https://docs.stophy.dev/production/rate-limits.md). |
| `500` to `504` | Stophy or the site you asked for is not answering. |

## Every error code

Retry only the codes marked Yes. Wait `retryAfterSeconds` when the answer has it. Otherwise back off. Wait 0.5 seconds, then 1 second, then 2 seconds. If the wait is longer than a minute, stop retrying. A `freeLimit` wait can be hours, so get an API key instead.

| Code | Status | Retry | What it means and what to do |
| - | - | - | - |
| `invalidRequest` | 400, 409 | No | The input is not valid, or a browser profile with that name already exists. `error` names the field. |
| `prohibitedPermission` | 400 | No | A [browser extension](https://docs.stophy.dev/browser/extensions.md) has a `key` field in its manifest, or asks for a permission that is not allowed. |
| `invalidCliSession`, `invalidCliVerifier` | 400 | No | A CLI sign-in session or verifier is not valid. Run `stophy login` again. |
| `apiKeyRequired` | 401 | No | The call needs an API key, because of the endpoint, paging or a field you sent. Get one at `signupUrl`, or call `signup`. |
| `unauthorized` | 401 | No | The key is not valid, has been revoked or has expired. |
| `insufficientCredits` | 402 | No | Your balance cannot cover the most the call can cost. Add money at [stophy.dev/billing](https://stophy.dev/billing). `requiredUsd` and `availableUsd` say by how much. |
| `forbidden` | 403 | No | This needs the Stophy dashboard. Sign in at stophy.dev and make the change there. |
| `siteNotRead` | 403 | No | Stophy does not read this site as a page. Use a [parser](https://docs.stophy.dev/scrape/prebuilt-parsers). |
| `promptInjectionDetected` | 403 | No | With `checkPromptInjection`, the page has text that tries to instruct an AI model. Nothing was returned or charged. Send `checkPromptInjection: false` to read it anyway. |
| `notFound` | 404, 410 | No | The endpoint, the page or the job does not exist. Check the id or the URL. Crawls, batches, extracts and scrapes expire after 24 hours. A 410 means the browser session has ended. |
| `cliSessionNotFound` | 404 | No | The CLI sign-in session was not found or has expired. |
| `methodNotAllowed` | 405 | No | The path takes another method. The `Allow` header names it. |
| `jobFinished` | 409 | No | The crawl, batch scrape or agent run already ended, so you cannot cancel it or add URLs to the batch. |
| `checkRunning` | 409 | No | A check of this monitor is already running. Wait for it to finish, then run it again. |
| `profileBusy` | 409 | Yes | Another call is saving to this browser profile. Wait, or send `saveChanges: false`. |
| `cliSessionExists`, `cliSessionCompleted` | 409 | No | The CLI sign-in session already exists, or is no longer pending. |
| `inviteClaimed` | 409 | No | You already claimed this invite. Its balance is in your account. |
| `inviteDisabled`, `inviteExpired`, `inviteUsedUp` | 410 | No | The invite link was turned off, has expired, or has been used up. Ask the sender for a new one. |
| `payloadTooLarge` | 413 | No | The request body is too large. Send a smaller body. |
| `profileTooLarge` | 413 | No | The browser profile is too large to save. Use a new profile name, or send `saveChanges: false`. |
| `unsupportedMediaType` | 415 | No | Send the body as JSON with `Content-Type: application/json`. |
| `freeLimit` | 429 | Yes | You used the free calls without an API key. Get an API key at `signupUrl`, or wait `retryAfterSeconds`. |
| `rateLimited` | 429 | Yes | Too many calls this minute, too many running at once, or too many browser sessions open. Wait `retryAfterSeconds`. |
| `internalError` | 500, 503 | Yes | The error is on Stophy's side, and the call cost nothing. Retry in a second. If it fails again, send support the `X-Request-ID`. |
| `sourceChanged` | 502 | No | The site answered in a shape Stophy could not read. Retrying will not help yet. |
| `busy` | 503, 409 | Yes | Stophy, or every browser, is busy. A 409 means a network policy or a proxy change on a session is still being applied. Wait `retryAfterSeconds`, 1 to 30 seconds. |
| `sourceUnavailable` | 503 | Yes | The site is not answering right now. Wait `retryAfterSeconds`. |
| `sourceRefused` | 503 | Yes | The site is refusing requests right now. Wait `retryAfterSeconds`. |
| `sourceTimeout` | 504 | Yes | The site took too long to answer. Try again. |

After the last try, stop and log the `requestId`. Three tries are enough for a retryable code. The CLI sign-in and invite codes come from signing in and invites, not from the data endpoints.

## Real errors

**No API key on an endpoint that needs one.** `401 apiKeyRequired`, from crawl.

```json theme={null}
{
  "success": false,
  "error": "This needs an API key. POST https://api.stophy.dev/v1/signup returns a claim link for your person to approve and a code that collects the key. Send it as Authorization: Bearer <key>.",
  "code": "apiKeyRequired",
  "retryable": false,
  "signupUrl": "https://stophy.dev/signup",
  "signup": "POST https://api.stophy.dev/v1/signup"
}
```

**A field that needs an API key.** `401 apiKeyRequired`, from a scrape without an API key that sent `waitFor`.

```json theme={null}
{
  "success": false,
  "error": "waitFor: Waiting on a page needs an API key. Get one at https://stophy.dev/signup, or leave waitFor out.",
  "code": "apiKeyRequired",
  "retryable": false
}
```

**A key that is not valid.** `401 unauthorized`. See [API keys](https://docs.stophy.dev/account/api-keys.md) for the body.

**A job that does not exist.** `404 notFound`, from `GET /v1/crawl/not-a-crawl`.

```json theme={null}
{
  "success": false,
  "error": "No crawl with that id. Results are kept for 24 hours.",
  "code": "notFound",
  "retryable": false
}
```

**The wrong method.** `405 methodNotAllowed`, from a `DELETE` to `/v1/scrape`.

```json theme={null}
{
  "success": false,
  "error": "This path only takes POST. Send a POST request with a JSON body.",
  "code": "methodNotAllowed",
  "retryable": false
}
```

**A site that is not answering.** `503 sourceUnavailable`, with a wait. See [Timeouts](https://docs.stophy.dev/production/timeouts.md).

```json theme={null}
{
  "success": false,
  "error": "The source is not answering right now. Try again shortly.",
  "code": "sourceUnavailable",
  "retryable": true,
  "retryAfterSeconds": 5
}
```

## A retry loop

This loop retries only when the answer says `retryable`, waits as long as the answer asks and stops after three tries.

```ts TypeScript theme={null}
async function call(path: string, input: object, attempts = 3) {
  for (let attempt = 0; ; attempt++) {
    const response = await fetch(`https://api.stophy.dev${path}`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(input),
      signal: AbortSignal.timeout(65_000),
    });
    const body = await response.json();
    if (response.ok) return body;
    if (!body.retryable || attempt + 1 >= attempts) {
      throw new Error(`${body.code}: ${body.error} (${response.headers.get("x-request-id")})`);
    }
    const seconds = body.retryAfterSeconds ?? 0.5 * 2 ** attempt;
    if (seconds > 60) throw new Error(`${body.code}: wait ${seconds} seconds`);
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  }
}

const page = await call("/v1/scrape", { url: "https://bun.com/docs/runtime/bunfig" });
```

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

import requests


def call(path, payload, attempts=3):
    for attempt in range(attempts):
        response = requests.post(
            f"https://api.stophy.dev{path}",
            headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
            json=payload,
            timeout=65,
        )
        body = response.json()
        if response.ok:
            return body
        if not body.get("retryable") or attempt + 1 >= attempts:
            raise RuntimeError(f"{body['code']}: {body['error']} ({response.headers.get('x-request-id')})")
        seconds = body.get("retryAfterSeconds", 0.5 * 2**attempt)
        if seconds > 60:
            raise RuntimeError(f"{body['code']}: wait {seconds} seconds")
        time.sleep(seconds)


page = call("/v1/scrape", {"url": "https://bun.com/docs/runtime/bunfig"})
```

The [SDKs](https://docs.stophy.dev/sdks) do this for you. They retry network errors and the statuses 429, 500, 502, 503 and 504, and throw a `StophyError` with the same fields.

## Report a problem

If an answer is wrong or differs from these docs, send [feedback](https://docs.stophy.dev/production/agent-feedback.md) with the `requestId`. To reach support, email [support@stophy.dev](mailto:support@stophy.dev) with the `requestId`.

## Related

* [Rate limits](https://docs.stophy.dev/production/rate-limits.md)
* [Timeouts](https://docs.stophy.dev/production/timeouts.md)
* [Usage and logs](https://docs.stophy.dev/production/usage-and-logs.md)
* [API errors reference](https://docs.stophy.dev/api-reference/errors.md)


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