Guides

Errors & responses

Every response is JSON with a status, a requestId, and accounting. Success is explicit; so are partial results and failures.

Status model

success

All supported fields for this bounded page or thread were retrieved. success is true.

partial

Usable data with omissions. Inspect coverage.warnings or coverage.reasons. HTTP status is still 200.

failed / challenged

No usable data. success is false and failure.code explains why.

Failure shape

Failed and challenged responses share one shape across the workers. The example is generated from the Bluesky contract.

JSON

{
  "requestId": "9d2f1c0a-6b1e-4c7d-9a8e-2f3b4c5d6e7f",
  "accounting": {
    "upstreamRequests": 0,
    "responseBytes": 0,
    "durationMs": 0
  },
  "success": false,
  "status": "failed",
  "failure": {
    "code": "invalid_request",
    "message": "string"
  }
}

HTTP status codes

HTTP	Meaning
400	Invalid request: missing, duplicate, unsupported or malformed parameters.
401	Missing or invalid customer key.
402	No available account credits. Add credits before retrying.
403	The public page reports restricted access.
404	The requested profile, post or resource does not exist publicly.
408	Request body deadline exceeded.
413	Request body exceeds the gateway byte limit.
429	Account or upstream rate limit reached. Respect retry-after.
502	Upstream challenge, unexpected response or bounded retrieval failure.
503	Authentication, gateway capacity or the requested platform is unavailable.
504	Operation deadline exceeded.

Failure codes

Code	Meaning	Workers
`invalid_request`	Missing, duplicate, ambiguous, unsafe or unsupported parameters.	Amazon, Bluesky, Couchsurfing, Depop, Etsy, Facebook Events, Facebook Marketplace, Facebook, GitHub, Hacker News, Instagram, Kick, Komi, Kwai, Lnk.Bio, LinkedIn Ads Library, LinkedIn, Linkme, Linktree, Meetup, Meta Ads Library, Pillar, Pinterest, Quora, Reddit, Rumble, Skool, Telegram, Threads, TikTok Shop, TikTok, Truth Social, Twitch, X (Twitter), Vinted, Whatnot, YouTube
`unauthorized`	Missing or invalid service key.	Amazon, Bluesky, Couchsurfing, Depop, Etsy, Facebook Events, Facebook Marketplace, Facebook, GitHub, Hacker News, Instagram, Kick, Komi, Kwai, Lnk.Bio, LinkedIn Ads Library, LinkedIn, Linkme, Linktree, Meetup, Meta Ads Library, Pillar, Pinterest, Quora, Rumble, Skool, Telegram, Threads, TikTok Shop, TikTok, Truth Social, Twitch, X (Twitter), Vinted, Whatnot, YouTube
`not_found`	The profile, post, clip or resource does not exist publicly.	Amazon, Bluesky, Couchsurfing, Depop, Etsy, Facebook Events, Facebook Marketplace, Facebook, GitHub, Hacker News, Instagram, Kick, Komi, Kwai, Lnk.Bio, LinkedIn Ads Library, LinkedIn, Linkme, Linktree, Meetup, Meta Ads Library, Pillar, Pinterest, Quora, Rumble, Skool, Telegram, Threads, TikTok Shop, TikTok, Truth Social, Twitch, X (Twitter), Vinted, Whatnot, YouTube
`upstream_challenged`	The platform answered with a bot challenge or login wall.	Amazon, Bluesky, Couchsurfing, Depop, Etsy, Facebook Events, Facebook Marketplace, Facebook, GitHub, Hacker News, Instagram, Kick, Komi, Kwai, Lnk.Bio, LinkedIn Ads Library, LinkedIn, Linkme, Linktree, Meetup, Meta Ads Library, Pillar, Pinterest, Quora, Rumble, Skool, Telegram, Threads, TikTok Shop, TikTok, Truth Social, Twitch, X (Twitter), Vinted, Whatnot, YouTube
`upstream_rate_limited`	The platform rate-limited the worker. Retry later.	Amazon, Bluesky, Couchsurfing, Depop, Etsy, Facebook Events, Facebook Marketplace, Facebook, GitHub, Hacker News, Instagram, Kick, Komi, Kwai, Lnk.Bio, LinkedIn Ads Library, LinkedIn, Linkme, Linktree, Meetup, Meta Ads Library, Pillar, Pinterest, Quora, Rumble, Skool, Telegram, Threads, TikTok Shop, TikTok, Truth Social, Twitch, X (Twitter), Vinted, Whatnot, YouTube
`upstream_error`	The platform returned an unexpected error or malformed response.	Amazon, Bluesky, Couchsurfing, Depop, Etsy, Facebook Events, Facebook Marketplace, Facebook, GitHub, Hacker News, Instagram, Kick, Komi, Kwai, Lnk.Bio, LinkedIn Ads Library, LinkedIn, Linkme, Linktree, Meetup, Meta Ads Library, Pillar, Pinterest, Quora, Reddit, Rumble, Skool, Telegram, Threads, TikTok Shop, TikTok, Truth Social, Twitch, X (Twitter), Vinted, Whatnot, YouTube
`unsupported_page`	The public page exists but its format is not supported.	Amazon, Bluesky, Couchsurfing, Depop, Etsy, Facebook Events, Facebook Marketplace, Facebook, GitHub, Hacker News, Instagram, Kick, Komi, Kwai, Lnk.Bio, LinkedIn Ads Library, LinkedIn, Linkme, Linktree, Meetup, Meta Ads Library, Pillar, Pinterest, Quora, Rumble, Skool, Telegram, Threads, TikTok Shop, TikTok, Truth Social, Twitch, X (Twitter), Vinted, Whatnot, YouTube
`response_too_large`	The upstream response exceeded the configured size limit.	Amazon, Bluesky, Couchsurfing, Depop, Etsy, Facebook Events, Facebook Marketplace, Facebook, GitHub, Hacker News, Instagram, Kick, Komi, Kwai, Lnk.Bio, LinkedIn Ads Library, LinkedIn, Linkme, Linktree, Meetup, Meta Ads Library, Pillar, Pinterest, Quora, Rumble, Skool, Telegram, Threads, TikTok Shop, TikTok, Truth Social, Twitch, X (Twitter), Vinted, Whatnot, YouTube
`unsafe_redirect`	The platform redirected to an unexpected host.	Amazon, Bluesky, Couchsurfing, Etsy, Facebook Events, Facebook Marketplace, Facebook, GitHub, Hacker News, Instagram, Kick, Komi, Kwai, Lnk.Bio, LinkedIn Ads Library, LinkedIn, Linkme, Linktree, Meetup, Meta Ads Library, Pillar, Pinterest, Quora, Rumble, Skool, Telegram, Threads, TikTok Shop, TikTok, Truth Social, Twitch, X (Twitter), Vinted, Whatnot, YouTube
`request_limit`	The bounded request budget for one operation was exhausted.	Amazon, Bluesky, Couchsurfing, Depop, Etsy, Facebook Events, Facebook Marketplace, Facebook, GitHub, Hacker News, Instagram, Kick, Komi, Kwai, Lnk.Bio, LinkedIn Ads Library, LinkedIn, Linkme, Linktree, Meetup, Meta Ads Library, Pillar, Pinterest, Quora, Rumble, Skool, Telegram, Threads, TikTok Shop, TikTok, Truth Social, Twitch, X (Twitter), Vinted, Whatnot, YouTube
`timeout`	The operation deadline elapsed.	Amazon, Bluesky, Couchsurfing, Depop, Etsy, Facebook Events, Facebook Marketplace, Facebook, GitHub, Hacker News, Instagram, Kick, Komi, Kwai, Lnk.Bio, LinkedIn Ads Library, LinkedIn, Linkme, Linktree, Meetup, Meta Ads Library, Pillar, Pinterest, Quora, Reddit, Rumble, Skool, Telegram, Threads, TikTok Shop, TikTok, Truth Social, Twitch, X (Twitter), Vinted, Whatnot, YouTube
`busy`	The worker is at its concurrency limit.	Amazon, Bluesky, Couchsurfing, Depop, Etsy, Facebook Events, Facebook Marketplace, Facebook, GitHub, Hacker News, Instagram, Kick, Komi, Kwai, Lnk.Bio, LinkedIn Ads Library, LinkedIn, Linkme, Linktree, Meetup, Meta Ads Library, Pillar, Pinterest, Quora, Rumble, Skool, Telegram, Threads, TikTok Shop, TikTok, Truth Social, Twitch, X (Twitter), Vinted, Whatnot, YouTube
`payload_too_complex`	The upstream payload was too deep or complex to process safely.	Amazon, Bluesky, Couchsurfing, Etsy, Facebook Events, Facebook Marketplace, Facebook, GitHub, Hacker News, Instagram, Kick, Kwai, LinkedIn Ads Library, LinkedIn, Linkme, Meetup, Meta Ads Library, Pillar, Pinterest, Quora, Rumble, Skool, Telegram, Threads, TikTok Shop, TikTok, Truth Social, Twitch, X (Twitter), Whatnot, YouTube
`unavailable_records`	See the platform reference.	Bluesky
`restricted_page`	The page is private or requires consent.	Bluesky, Facebook Events, Facebook Marketplace, Facebook, Instagram, Kick, Komi, LinkedIn Ads Library, Linkme, Linktree, Meta Ads Library, Pillar, Pinterest, Telegram, Threads, TikTok, Truth Social, Twitch, X (Twitter), YouTube
`restricted`	See the platform reference.	Couchsurfing, Depop, Kwai, LinkedIn, Meetup, Rumble, Skool
`upstream_pending`	See the platform reference.	GitHub
`count_estimated_only`	See the platform reference.	Instagram
`operation_unavailable`	See the platform reference.	Instagram, Threads, X (Twitter)
`search_unavailable`	See the platform reference.	LinkedIn, Quora, Threads
`search_failed`	See the platform reference.	LinkedIn, Quora, Threads
`member_not_on_page`	See the platform reference.	Meetup
`transcription_unavailable`	See the platform reference.	Meta Ads Library
`transcription_failed`	See the platform reference.	Meta Ads Library
`transcription_too_long`	See the platform reference.	Meta Ads Library
`public_client_unavailable`	See the platform reference.	Pillar, Twitch
`account_metadata_unavailable`	See the platform reference.	Pillar
`challenge_detected`	See the platform reference.	Reddit
`breaker_open`	Thread retrieval is temporarily paused after repeated proxy failures.	Reddit
`partial_results`	See the platform reference.	Reddit
`upstream_graphql_error`	See the platform reference.	Twitch
`invalid_continuation`	See the platform reference.	YouTube
`age_restricted`	See the platform reference.	YouTube

Reading the data

Unknown metrics are null, never zero. Preserve nulls when you store results.
Coverage describes the returned page or thread. It does not imply all historical content.
Check status even on HTTP 200. Only retry on codes that suggest a transient cause such as upstream_rate_limited, timeout or busy.
accounting reports upstream requests, bytes and duration so you can budget calls.