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

# Errors

> Every Stophy error code with its HTTP status, whether to retry and the fix. All errors share one flat JSON body, and a failed call costs nothing.

Every failed call returns one flat JSON body and costs nothing. Read `code` to decide whether to fix the request or retry it. This is the answer to `{"colour": "red"}` sent to scrape, with the field list cut.

```json theme={null}
{
  "success": false,
  "error": "Unknown field `colour`. Fields: formats, onlyMainContent, onlyCleanContent, …",
  "code": "invalidRequest",
  "retryable": false,
  "requestId": "4897a792-9571-47d6-bfd4-5a3db0a7c022"
}
```

| Field | Meaning |
| - | - |
| `error` | What went wrong and what to do next |
| `code` | A stable code from the table below |
| `retryable` | `true` when the same call can work later |
| `retryAfterSeconds` | Seconds to wait, also the `Retry-After` header. When absent, back off as in [Troubleshooting](https://docs.stophy.dev/production/troubleshooting.md#retry). |
| `requestId` | Also the `X-Request-ID` header. Send it to support. |
| `requiredUsd`, `availableUsd`, `billingUrl` | On `insufficientCredits`: the most the call can cost, your balance, and where to add money. `requiredCredits` and `availableCredits` are older fields for the same numbers. |
| `signupUrl`, `signup` | On `apiKeyRequired`, `freeLimit` and an invalid key: where a person gets a key, and the `POST https://api.stophy.dev/v1/signup` call for an agent. See [Get credentials](https://docs.stophy.dev/get-credentials.md). |

## Request, key and account

| Code | Status | Retry | Fix |
| - | - | - | - |
| `invalidRequest` | 400, 409 | No | `error` names the field. A 409 means the name is taken or the thing is not ready for the change. [Deleting a recording](https://docs.stophy.dev/api-reference/endpoint/browser-recording-delete.md) while `recordingStatus` is processing returns 409: wait for `ready` or `failed`. |
| `prohibitedPermission` | 400 | No | The extension's `manifest.json` has a `key` field or asks for a permission that is not allowed. |
| `apiKeyRequired` | 401 | No | The operation, paging or a field you sent needs a key. Get one at `signupUrl` or call `signup`. |
| `unauthorized` | 401 | No | The key is wrong, revoked or expired. |
| `insufficientCredits` | 402 | No | The balance cannot cover the most the call can cost. Nothing was charged. Add money at `billingUrl`. See [Pricing](https://docs.stophy.dev/account/pricing.md#balance). |
| `forbidden` | 403 | No | This needs the dashboard. Sign in at stophy.dev. |
| `notFound` | 404, 410 | No | The path, page, ID or job does not exist, or a job result is older than 24 hours. A 410 means the browser session ended. |
| `methodNotAllowed` | 405 | No | The `Allow` header names the method. |
| `jobFinished` | 409 | No | The crawl, batch or agent run already ended: you cannot cancel it or add URLs. |
| `checkRunning` | 409 | No | A check of this monitor is running. Wait, then run it again. |
| `profileBusy` | 409 | Yes | Another call is saving to this browser profile. Wait, or send `saveChanges: false`. |
| `payloadTooLarge` | 413 | No | Send a smaller body. |
| `profileTooLarge` | 413 | No | The profile is too large to save. Use a new profile name or send `saveChanges: false`. |
| `unsupportedMediaType` | 415 | No | Send JSON with `Content-Type: application/json`. |
| `freeLimit` | 429 | Yes | Keyless limit used. Get a key at `signupUrl` or wait `retryAfterSeconds`. A daily wait can be hours. |
| `rateLimited` | 429 | Yes | A limit in [Rate limits](https://docs.stophy.dev/production/rate-limits.md#when-you-go-over). Wait `retryAfterSeconds`. |
| `internalError` | 500, 503 | Yes | Stophy failed and the call cost nothing. Retry in a second. If it fails again, send support the `requestId`. |
| `busy` | 503, 409 | Yes | Stophy or every browser is busy. Wait `retryAfterSeconds`: 5 when Stophy is busy, 30 when every browser is. A 409 means a network policy or proxy change on a session is still being applied. |

## The site you read

These come from the site a call reads, not from your request.

| Code | Status | Retry | Fix |
| - | - | - | - |
| `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 | `checkPromptInjection` found text that instructs an AI model. Nothing was returned or charged. Send `checkPromptInjection: false` to read the page anyway. See [Safety](https://docs.stophy.dev/scrape/safety.md). |
| `sourceChanged` | 502 | No | The site answered in a shape Stophy could not read. Retrying will not help yet. |
| `sourceUnavailable` | 503 | Yes | The site is not answering. Wait `retryAfterSeconds`. |
| `sourceRefused` | 503 | Yes | The site is refusing requests. Wait `retryAfterSeconds`. |
| `sourceTimeout` | 504 | Yes | The site took too long. Wait `retryAfterSeconds` (5), or raise `timeout`, see [Timeouts](https://docs.stophy.dev/production/timeouts.md). |

## CLI sign-in and invites

Only the CLI login and invite links return these, never a data endpoint.

| Code | Status | Retry | Fix |
| - | - | - | - |
| `invalidCliSession`, `invalidCliVerifier` | 400 | No | The CLI sign-in session or verifier is not valid. Run `stophy login` again. |
| `cliSessionNotFound` | 404 | No | The CLI sign-in session was not found or has expired. |
| `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 is used up. Ask the sender for a new one. |

`insufficientCredits` keeps its name, and its message and fields are in dollars.


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