Working with it
Errors
Every code, what it means, what to do.
SnoopScan uses conventional HTTP status codes. Every error has the same shape: branch on error.code, not the message.
{ "success": false, "error": { "code": "BLOCKED", "message": "The site blocked the request", "detail": { "status_code": 403 } }}
Error codes
| Code | HTTP | What to do |
|---|---|---|
INVALID_REQUEST | 400 | The body did not validate. The message names the field. Fix and retry. |
UNAUTHORIZED | 401 | Missing, mistyped or revoked key. Check the Authorization header. |
ROBOTS_DENIED | 403 | The site's robots rules disallow it. Retrying will not change that. |
JOB_NOT_FOUND | 404 | No job with that id, or it has expired. |
RATE_LIMITED | 429 | Too many requests. Retry with exponential backoff, or upgrade your plan. |
TARGET_ERROR | 502 | The site returned an error. Its status is in detail.status_code. Check the URL. |
FETCH_FAILED | 502 | The site could not be reached (DNS, TLS or a refused connection). Retry once. |
BLOCKED | 502 | The site blocked the request. Retry later, or set location to try from another country. |
TIMEOUT | 504 | The page took longer than your timeout. Raise it, or remove waitFor. |
EXTRACTION_FAILED | 500 | The page loaded but had no readable content. Try another format. Also returned when one of your actions could not run: the message names the step. Check the page has not changed, or add a wait step. |
INSUFFICIENT_CREDITS | 402 | You are out of credits. Nothing was charged. Upgrade your plan or wait for your monthly credits. |
PLAN_REQUIRED | 402 | Saving or running a Mentions watch needs a Mentions plan, or today’s previews are used up. Nothing was charged. Choose a plan on the Pricing page. |
FORBIDDEN_SCOPE | 403 | The key does not have permission for this endpoint. detail.scope names the permission. Add it under API keys → Edit; the key itself does not change. |
ENGINE_REFUSED | 503 | The request was not attempted and nothing was charged. If detail.minutes is set, retry after that many minutes. If detail.signal is tier_ceiling_below_floor, the page needs a higher maxTier than you set: raise it. |
SEARCH_UNAVAILABLE | 503 | Search is temporarily unavailable. Nothing was charged. Retry later. |
SERP_UNAVAILABLE | 503 | Search results are temporarily unavailable. Nothing was charged. Retry later. |
PROXY_UNAVAILABLE | 503 | The requested proxy mode is not available. Nothing was charged. Use auto. |
PLACES_UNAVAILABLE, PLATFORMS_UNAVAILABLE, COMPANY_UNAVAILABLE | 503 | The endpoint is only available on the hosted API at https://api.snoopscan.com, not on a self-hosted copy. |
INTERNAL | 500 | Something went wrong on our side. Retry, and contact us if it keeps happening. |
Retries
Retry FETCH_FAILED, TIMEOUT and RATE_LIMITED with exponential backoff. Do not retry INVALID_REQUEST, UNAUTHORIZED or ROBOTS_DENIED: the same request fails the same way.
Errors are free. No error is charged, so retries never use up your credits.