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.
{
"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. |
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. |
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 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. |
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. 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. |
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. |
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. |
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.