Scrape Everything
ErrorsMenu

Errors

Errors use standard HTTP status codes and a stable, machine readable code. Branch on code, not on message.

Error format

404 Not Found
{
  "success": false,
  "message": "User not found",
  "code": "NOT_FOUND",
  "request_id": "req_Lx2n9Wq0Tb7Zc4Kp1Mv8",
  "meta": { "credits_charged": 1, "credits_remaining": 41 }
}

message is written for humans and may change. code is stable. meta appears on most errors from a scraping endpoint and says what the request cost: credits_charged, plus credits_remaining when your balance was touched. Errors that stop a request earlier (for example a missing or invalid key, invalid JSON or an unknown endpoint) have no meta and are not charged.

Error codes

StatusCodeMeaningCharged
400VALIDATION_ERRORA parameter is missing or invalid. The message says which one. A limit above the endpoint's maximum is not an error: it is lowered to the maximum.No
400INVALID_JSONThe body is not valid JSON.No
400API_KEY_IN_URLThe API key was sent in the URL.No
401AUTH_REQUIREDNo API key was sent.No
401INVALID_API_KEYThe API key is unknown or revoked.No
402INSUFFICIENT_CREDITSYour balance is lower than the endpoint's cost.No
403IP_NOT_ALLOWEDThe key is restricted to other IP addresses.No
403ACCOUNT_SUSPENDEDThe account is suspended.No
404UNKNOWN_ENDPOINTThe path does not match an endpoint.No
404NOT_FOUNDThe account, post or video does not exist.Yes
404PRIVATE_ACCOUNTThe content exists but is private.Yes
404AGE_RESTRICTEDThe content requires a logged in, age verified account.Yes
404LOGIN_REQUIREDThe profile is only shown to logged in users.Yes
404NO_TRANSCRIPTThe video has no captions or transcript.Yes
404COMMENTS_DISABLEDComments are turned off for the video.Yes
404NOT_A_REELThe Instagram link is a post, not a reel.Yes
413PAYLOAD_TOO_LARGEThe request body is larger than 100 KB.No
429RATE_LIMITEDToo many requests this minute.No
429CONCURRENCY_LIMITToo many requests running at once.No
422ESTIMATE_ONLYInstagram post count: only a rounded count is visible and allow_estimated was not sent.No
429AUTH_BLOCKEDToo many failed authentication attempts from your IP.No
429TOO_MANY_FAILURESToo many refunded failures on your account within 10 minutes. Wait a few minutes.No
503TARGET_BLOCKEDThe platform blocked every attempt.No, refunded
503PARSE_ERRORThe platform returned a response we could not read.No, refunded
503PROXY_CONNECT_FAILEDA network error occurred on our side.No, refunded
503NO_PROXY_AVAILABLECapacity is temporarily exhausted.No, refunded
503SEARCH_UNAVAILABLESearch is temporarily unavailable.No, refunded
503TEMPORARILY_UNAVAILABLEThe endpoint is temporarily unavailable.No, refunded
503TIMEOUTThe platform did not answer in time.No, refunded
500INTERNAL_ERRORSomething went wrong on our side.No, refunded

Which errors to retry

Retry 429 after the reset time, and 503 with exponential backoff; the code field tells you why. A 404 is a final answer for that target: retrying returns the same result and is charged again, so cache it on your side or use cache_days.

Check the HTTP status before you parse the body. API errors always use the JSON format above. If the API itself cannot be reached, the network in front of it can answer with a 502 or 504 HTML page that has no code and no request_id: treat it as retryable and back off.

Contacting support? Include the request_id from the response or the X-Request-Id header. It lets us find the exact request in seconds.