ErrorsMenu
Errors
Errors use standard HTTP status codes and a stable, machine readable code. Branch on code, not on message.
Error format
{
"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
| Status | Code | Meaning | Charged |
|---|---|---|---|
| 400 | VALIDATION_ERROR | A 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 |
| 400 | INVALID_JSON | The body is not valid JSON. | No |
| 400 | API_KEY_IN_URL | The API key was sent in the URL. | No |
| 401 | AUTH_REQUIRED | No API key was sent. | No |
| 401 | INVALID_API_KEY | The API key is unknown or revoked. | No |
| 402 | INSUFFICIENT_CREDITS | Your balance is lower than the endpoint's cost. | No |
| 403 | IP_NOT_ALLOWED | The key is restricted to other IP addresses. | No |
| 403 | ACCOUNT_SUSPENDED | The account is suspended. | No |
| 404 | UNKNOWN_ENDPOINT | The path does not match an endpoint. | No |
| 404 | NOT_FOUND | The account, post or video does not exist. | Yes |
| 404 | PRIVATE_ACCOUNT | The content exists but is private. | Yes |
| 404 | AGE_RESTRICTED | The content requires a logged in, age verified account. | Yes |
| 404 | LOGIN_REQUIRED | The profile is only shown to logged in users. | Yes |
| 404 | NO_TRANSCRIPT | The video has no captions or transcript. | Yes |
| 404 | COMMENTS_DISABLED | Comments are turned off for the video. | Yes |
| 404 | NOT_A_REEL | The Instagram link is a post, not a reel. | Yes |
| 413 | PAYLOAD_TOO_LARGE | The request body is larger than 100 KB. | No |
| 429 | RATE_LIMITED | Too many requests this minute. | No |
| 429 | CONCURRENCY_LIMIT | Too many requests running at once. | No |
| 422 | ESTIMATE_ONLY | Instagram post count: only a rounded count is visible and allow_estimated was not sent. | No |
| 429 | AUTH_BLOCKED | Too many failed authentication attempts from your IP. | No |
| 429 | TOO_MANY_FAILURES | Too many refunded failures on your account within 10 minutes. Wait a few minutes. | No |
| 503 | TARGET_BLOCKED | The platform blocked every attempt. | No, refunded |
| 503 | PARSE_ERROR | The platform returned a response we could not read. | No, refunded |
| 503 | PROXY_CONNECT_FAILED | A network error occurred on our side. | No, refunded |
| 503 | NO_PROXY_AVAILABLE | Capacity is temporarily exhausted. | No, refunded |
| 503 | SEARCH_UNAVAILABLE | Search is temporarily unavailable. | No, refunded |
| 503 | TEMPORARILY_UNAVAILABLE | The endpoint is temporarily unavailable. | No, refunded |
| 503 | TIMEOUT | The platform did not answer in time. | No, refunded |
| 500 | INTERNAL_ERROR | Something 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.
request_id from the response or the X-Request-Id header. It lets us find the exact request in seconds.