API errors | Stophy

Send a field the endpoint does not take and read the error.

curl -X POST https://api.stophy.dev/v1/scrape \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://bun.com","colour":"red"}'

Response

The status is 400. The list of fields is cut.

{
  "success": false,
  "error": "Unknown field `colour`. Fields: url, formats, onlyMainContent, onlyCleanContent, includeTags, excludeTags, maxAge, …",
  "code": "invalidRequest"
}

Every error has this flat shape.

Field	What it is
`success`	Always `false`.
`error`	What went wrong and what to do next, in plain words.
`code`	A stable code from the table below.
`retryAfterSeconds`	Present when you should wait a set time. The `Retry-After` header has the same value. When it is absent, back off as Errors and retries says.
`signupUrl`	Present on `apiKeyRequired`, `freeLimit` and a key that is not valid. Where a person gets a key.
`signup`	Sent next to `signupUrl`: `POST https://api.stophy.dev/v1/signup`, the call that gets an agent a key. See Sign up.

The X-Request-ID header names the request. Include it when you contact support.

Error codes

Code	Status	Retry	What it means
`invalidRequest`	400	No	The input is not valid. The error names the field.
`apiKeyRequired`	401	No	This call needs an API key: the endpoint, paging or a field you sent.
`unauthorized`	401	No	The API key is not valid or has expired.
`insufficientCredits`	402	No	Your balance is too low for this call, and nothing was charged. The `x-required-credits` and `x-available-credits` headers say by how much. Top up.
`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.
`notFound`	404	No	The endpoint, the page or the job does not exist.
`methodNotAllowed`	405	No	The path takes another method. The `Allow` header names it.
`jobFinished`	409	No	The crawl or batch scrape already ended, so there is nothing to cancel.
`profileBusy`	409	No	Another call is using this browser profile.
`payloadTooLarge`	413	No	The request body is too large.
`profileTooLarge`	413	No	The browser profile is too large to save.
`unsupportedMediaType`	415	No	Send the body as JSON with `Content-Type: application/json`.
`freeLimit`	429	Yes	You used the free calls without a key. Get a key at `signupUrl`, or wait `retryAfterSeconds`.
`rateLimited`	429	Yes	Too many requests. Wait `retryAfterSeconds`.
`internalError`	500, 503	Yes	That one is on us, and it 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.
`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.

Real errors

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

{
  "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",
  "signupUrl": "https://stophy.dev/signup",
  "signup": "POST https://api.stophy.dev/v1/signup"
}

A key that is not valid. 401 unauthorized.

{
  "success": false,
  "error": "This API key is not valid or has expired. 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": "unauthorized",
  "signupUrl": "https://stophy.dev/signup",
  "signup": "POST https://api.stophy.dev/v1/signup"
}

A path that is not an endpoint. 404 notFound, from a removed path like /v1/google/search.

{
  "success": false,
  "error": "No endpoint at this path. See every endpoint at https://api.stophy.dev/openapi.json",
  "code": "notFound"
}

A domain with no website. 404 notFound, from scrape.

{
  "success": false,
  "error": "That address has no website behind it. Check the spelling of the domain, then try again.",
  "code": "notFound"
}

Account codes

These come from signing in to the CLI and from invites, not from a data endpoint.

Code	Status	What it means
`invalidCliSession`	400	The sign-in session is not valid.
`invalidCliVerifier`	400	The sign-in verifier is not valid.
`cliSessionNotFound`	404	The sign-in session was not found or has expired.
`cliSessionExists`	409	The sign-in session already exists.
`cliSessionCompleted`	409	The sign-in session is no longer pending.
`inviteClaimed`	409	You already claimed this invite.
`inviteDisabled`	410	This invite link was turned off.
`inviteExpired`	410	This invite link has expired.
`inviteUsedUp`	410	This invite link has been used up.

Retrying

Retry only the codes marked Yes. Errors and retries has the wait and the most tries for each code, and a retry loop for TypeScript and Python.

Using the API

Read pages

Crawl a site

Batch scrape

Extract

Browser tasks

Catalog

Account

Errors

Error codes

Real errors

Account codes

Retrying

​Error codes

​Real errors

​Account codes

​Retrying

Error codes

Real errors

Account codes

Retrying