Skip to main content
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 before you retry. A failed call costs nothing, so a retry costs nothing extra.
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

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. 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.
A field that needs an API key. 401 apiKeyRequired, from a scrape without an API key that sent waitFor.
A key that is not valid. 401 unauthorized. See API keys for the body. A job that does not exist. 404 notFound, from GET /v1/crawl/not-a-crawl.
The wrong method. 405 methodNotAllowed, from a DELETE to /v1/scrape.
A site that is not answering. 503 sourceUnavailable, with a wait. See Timeouts.

A retry loop

This loop retries only when the answer says retryable, waits as long as the answer asks and stops after three tries.
The 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 with the requestId. To reach support, email support@stophy.dev with the requestId.