Error codes - Scrapebento Docs

Errors use the standard envelope:

{ "error": { "code": "challenge", "message": "target returned an anti-bot challenge" } }

Branch on code, not on the message. Codes are stable; messages are not.

A job that ran and failed is reported as HTTP 200 with status: "failed" and a terminal error — the request succeeded, the scrape did not. Only failures that happen before or instead of a job use the error envelope above. See Jobs & Webhooks.

Your request needs changing

Retrying these unchanged will fail the same way.

Code	HTTP	Means
`bad_request`	400	The input is malformed or a required field is missing.
`invalid_url`	400	The URL failed validation.
`invalid_provider`	400	Unknown search provider.
`invalid_mode`	400	Unknown mode for this endpoint.
`invalid_webhook_url`	400	`webhookUrl` is not a valid public http(s) URL.
`ssrf_blocked`	400	The target resolves to a private, loopback, or link-local address.
`unsupported`	422	The endpoint cannot serve this combination of options.
`unsupported_platform`	422	That platform is not supported for this endpoint.
`insufficient_credits`	402	Not enough credits. Check `/v1/public/balance`.
`endpoint_not_enabled`	403	The endpoint is restricted and your organization is not entitled to it.
`webhook_registration_failed`	503	The webhook destination could not be recorded. The request was fine; retry it.

endpoint_not_enabled is not a token problem, and minting a new key will not fix it. A few endpoints are restricted to organizations that have been granted them; the restriction is on the organization, not the credential. Contact support to request access. This is distinct from insufficient_scope, which means the token you sent was issued without the scope this method needs — that one you can fix yourself by issuing a token that has it.

The target refused or had nothing

The request was fine; the target was the problem.

Code	HTTP	Means	Refunded
`challenge`	403	An anti-bot wall or CAPTCHA.	Yes
`login_required`	403	The target requires authentication.	Yes
`forbidden`	403	Refused with no challenge — usually a geo-block or IP denylist.	Yes
`not_found`	404	The target does not exist.	No
`unresolved_handle`	404	The handle or username could not be resolved.	No
`dns_not_found`	404	The domain does not resolve.	No
`dns_no_address`	404	The domain resolves but has no address.	No
`domain_parked`	422	The domain is parked, not a real site.	No
`bad_feed`	422	The feed could not be parsed.	No
`extraction_error`	422	The page was fetched but could not be extracted completely.	Yes

challenge, login_required, and forbidden all mean you received no content, so all three are refunded. They are reported separately because they call for different responses: a challenge may succeed from a different route, while a login wall never will.

Temporary — retry with backoff

Code	HTTP	Means
`rate_limited`	429	The target rate-limited us. Honour `Retry-After`.
`too_many_in_flight`	429	Your organization already has the maximum number of jobs queued or running. Nothing was charged; the limit clears as your own jobs finish.
`test_quota_exhausted`	429	A test key has spent its organization’s allowance for the current 24-hour window. Nothing was charged. The window is trailing, so it refills continuously; a live key clears it immediately.
`timeout`	504	The scrape did not finish inside its budget.
`worker_timeout`	504	The job exceeded its processing ceiling.
`upstream_error`	502	The target or a provider returned an error.
`transport`	502	The connection failed before a usable response.
`connect_failed`	502	The connection could not be established.
`tls_invalid`	502	The target’s TLS certificate is invalid.
`dns_resolution_failed`	502	DNS resolution failed at the network layer.
`provider_error`	502	An upstream data provider rejected a request we consider valid.
`provider_data_missing`	502	An upstream provider had no data for a target that may still be valid.
`empty_serp`	502	Search providers returned nothing after exhausting routes.
`broker_unavailable`	503	The job queue is unavailable.
`dispatch_failed`	503	The job could not be enqueued.

All of these are refunded. provider_error and provider_data_missing are permanent for a given attempt despite the 502 — an immediate repeat reaches the same answer — so both are refunded but neither is worth retrying straight away. provider_data_missing differs in that the target may simply have no data yet: a scrape scheduled for later is still worth running, where a rejected input will keep being rejected.

Ours

Code	HTTP	Means
`not_configured`	424	An operator-side dependency is missing. Refunded.
`internal_error`	500	A defect on our side. Refunded.
`credit_action_unconfigured`	500	The action has no configured credit cost.
`result_unavailable`	410	The job succeeded but its result has been purged.
`result_too_large`	413	The result exceeded the size cap.

Refunds

You are not charged for a job that returned no content. Refunds are automatic and land within a minute — you do not need to ask. Confirm with:

curl -H "Authorization: Bearer $SCRAPEBENTO_API_KEY" \
  "$SCRAPEBENTO_API/v1/public/usage?days=7"

creditsSpent and creditsRefunded are reported separately per action, so you can see refunds rather than inferring them from a smaller total. What is not refunded is a job that gave you a correct answer you did not want: not_found, domain_parked, bad_feed, and the caller-error codes. We did the work and the answer is real — the target genuinely is not there.

​Your request needs changing

​The target refused or had nothing

​Temporary — retry with backoff

​Ours

​Refunds

Your request needs changing

The target refused or had nothing

Temporary — retry with backoff

Ours

Refunds