Errors
Errors return a non-2xx status and a JSON body with a human-readable error message plus a machine-readable code where useful.
Errors return a non-2xx status and a JSON body with a human-readable error message, plus a machine-readable code where useful. Scraper input errors add a details string naming the bad field. Branch on code, not on the message text: messages get reworded, codes do not.
400Invalid product, quantity, targeting or scraper input.401Missing or invalid API key.402Wallet balance short, or per-key daily spend cap reached.403Key is missing the required scope, or the platform refused access to the target.404Unknown scraper, or the target does not exist (private, deleted, wrong handle).429Rate limited. Slow down and retry (Retry-After header).502Transient failure fetching from the platform. Retry shortly. Never billed.503The scraper is temporarily unavailable on our side. Retry shortly. Never billed.Scraper error codes
A failed scrape names its cause in code so you can handle each one differently instead of retrying everything. No failed scrape is ever billed, whatever the cause.
| code | Status | Description |
|---|---|---|
target_not_found | 404 | The profile, post or ID is not there. Private, deleted, or the handle is wrong. Retrying will not help; fix the input. |
target_restricted | 403 | The platform refused it: age-gated, region-locked or login-only content. Retrying will not help. |
bad_input | 400 | The endpoint rejected these parameters. Check the required parameters for that endpoint. Several accept one of a pair (a handle or a user id) and reject a call carrying neither. |
provider_failed | 502 | A transient fetch failure. Safe and sensible to retry, ideally with a short backoff. |
upstream_credits_exhausted | 503 | A capacity problem on our side, not a problem with your request. Retry shortly; if it persists, contact us. |
upstream_auth_rejected | 503 | As above: ours to fix, not yours. Retry shortly and tell us if it continues. |
Error response
{
"error": "No data found for this target. It may be private, deleted, or the handle/URL may be wrong.",
"code": "target_not_found"
}Changed recently
Before 2026-07-30 every failed scrape answered 502 with the same generic message, so a mistyped handle looked identical to an outage. The statuses and codes above are what the API returns now.Need a hand wiring this up? Email support@hproxy.com. A real person reads every message.