docs / error codes · updated 2026-07-20
Error codes reference
Every apihq actor reports failure the same way: the item becomes a success: false row in the same dataset as the successes, carrying a stable machine-readable code, a human-readable error, a request_id for support tracing, and an HTTP-style status_code field. A failed item is never billed, and an item-level miss becomes a row while the batch continues — run-level infrastructure failures are a separate, rarer category handled by the Apify platform. Codes are stable across releases, so pipelines branch on the code instead of parsing error text.
{
"success": false,
"code": "NO_CAPTIONS",
"error": "Video has no caption tracks.",
"request_id": "req_911f37d2e556",
"status_code": 404
}Codes every actor can return
| code | billed | meaning |
|---|---|---|
| VALIDATION_FAILED | $0.0000 | The input did not parse as a valid ID, URL, @handle, keyword, or package name for that actor. The exact accepted formats are on each API's page. |
| DEADLINE_EXCEEDED | $0.0000 | The per-item deadline (30 seconds) was hit before the fetch finished — an upstream or proxy stall becomes a typed row with status_code 504 instead of a hung run. |
YouTube Transcript Scraper
| NO_CAPTIONS | $0.0000 | The video has no caption track at all. |
| PLAYABILITY | $0.0000 | The video is private, deleted, age-gated, or otherwise not playable. |
| EMPTY_TRANSCRIPT | $0.0000 | The caption track parsed to zero segments. Treated as a failure, so you never pay for a blank transcript. |
| VALIDATION_FAILED | $0.0000 | The input was not a valid 11-character video ID. |
| DEADLINE_EXCEEDED | $0.0000 | The 30-second per-video deadline was hit. Returned as an unbilled row with status_code 504. |
| PO_TOKEN_REQUIRED | $0.0000 | YouTube demanded a proof-of-origin token for this request. |
| CAPTIONS_TIMEOUT | $0.0000 | The caption fetch itself timed out. |
| NO_INPUT | $0.0000 | No video IDs were provided. |
YouTube Channel Scraper
| CHANNEL_NOT_FOUND | $0.0000 | The URL, @handle, or ID could not be resolved to a channel. |
| NO_VIDEOS | $0.0000 | The channel exists but has no long-form uploads. |
| VALIDATION_FAILED | $0.0000 | The input was not a valid channel URL, @handle, or UC… ID. |
| RESOLVE_TIMEOUT | $0.0000 | Resolving the channel identity timed out. |
| CHANNEL_VIDEOS_TIMEOUT | $0.0000 | Listing the channel's videos timed out. |
| DEADLINE_EXCEEDED | $0.0000 | The per-channel deadline was hit. No charge. |
YouTube Shorts Scraper
| CHANNEL_NOT_FOUND | $0.0000 | The URL, @handle, or ID could not be resolved to a channel. |
| NO_SHORTS | $0.0000 | The channel exists but has never posted a Short. |
| VALIDATION_FAILED | $0.0000 | The input was not a valid channel URL, @handle, or UC… ID. |
| RESOLVE_TIMEOUT | $0.0000 | Resolving the channel identity timed out. |
| CHANNEL_SHORTS_TIMEOUT | $0.0000 | Listing the channel's Shorts timed out. |
| DEADLINE_EXCEEDED | $0.0000 | The per-channel deadline was hit. No charge. |
YouTube Comments Scraper
| VIDEO_NOT_FOUND | $0.0000 | The video is deleted, private, or the ID does not exist. |
| COMMENTS_DISABLED | $0.0000 | The video exists but has comments turned off. |
| VALIDATION_FAILED | $0.0000 | The input was not a recognizable video URL or 11-character ID. |
| VIDEO_COMMENTS_TIMEOUT | $0.0000 | Listing the video's comments timed out. |
| DEADLINE_EXCEEDED | $0.0000 | The 30-second per-page deadline was hit. Returned as an unbilled row with status_code 504. |
YouTube Search Scraper
| NO_RESULTS | $0.0000 | The query returned no results. The row is retained, unbilled. |
| VALIDATION_FAILED | $0.0000 | The input was not a usable query or filter value. |
| SEARCH_TIMEOUT | $0.0000 | The search request itself timed out. |
| DEADLINE_EXCEEDED | $0.0000 | The 30-second per-page deadline was hit. Returned as an unbilled row with status_code 504. |
Google Play Reviews Scraper
| NO_REVIEWS | $0.0000 | The app has no reviews in the requested locale, or the app does not exist. |
| VALIDATION_FAILED | $0.0000 | The input was not a recognizable package name or Play Store URL. |
| PLAY_REVIEWS_TIMEOUT | $0.0000 | Listing the app's reviews timed out. |
| DEADLINE_EXCEEDED | $0.0000 | The 30-second per-page deadline was hit. Returned as an unbilled row with status_code 504. |
App Store Reviews Scraper
| NO_REVIEWS | $0.0000 | The app has no reviews in the requested storefront, or the app does not exist. |
| VALIDATION_FAILED | $0.0000 | The input was not a recognizable numeric app ID or apps.apple.com URL. |
| APP_STORE_RATE_LIMITED | $0.0000 | Apple rate-limited the walk. Delivered reviews are kept; the remaining walk stops and the run still succeeds. |
| APP_STORE_OVERLOAD | $0.0000 | The extraction service shed the request under load. Early stop; delivered reviews are kept. |
| APP_STORE_UPSTREAM_UNAVAILABLE | $0.0000 | Apple was unavailable. Early stop; delivered reviews are kept. |
| APP_STORE_REVIEWS_TIMEOUT | $0.0000 | Listing the app's reviews timed out. Early stop; delivered reviews are kept. |
| DEADLINE_EXCEEDED | $0.0000 | The per-request deadline was hit. Returned as an unbilled row with status_code 504. |
| NO_INPUT | $0.0000 | No usable app ID was provided. |
TripAdvisor Reviews Scraper
| NO_REVIEWS | $0.0000 | The location has no reviews, or the location does not exist. |
| NO_MATCHING_REVIEWS | $0.0000 | The location has reviews, but none match the filters you set. |
| VALIDATION_FAILED | $0.0000 | The input was not a valid TripAdvisor URL or numeric location ID. |
| INVALID_FILTER | $0.0000 | A supplied filter had no valid value (e.g. ratings: [6]). The run stops before any request so you are never charged for reviews outside the filter you intended. |
| PAGINATION_STALLED | $0.0000 | One location stopped early after repeated pages returned nothing new. The batch continues. |
| TRIPADVISOR_CHALLENGED | $0.0000 | TripAdvisor's anti-bot layer challenged the request. Early stop: delivered reviews are kept and the run still succeeds. |
| TRIPADVISOR_UPSTREAM | $0.0000 | TripAdvisor was unavailable. Early stop; delivered reviews are kept. |
| NO_FRESH_IP | $0.0000 | The extraction service had no fresh session capacity. Early stop; delivered reviews are kept. |
| POOL_STOPPED | $0.0000 | The extraction service's session pool stopped. Early stop; delivered reviews are kept. |
| MINT_BLOCKED | $0.0000 | The extraction service could not establish a new session. Early stop; delivered reviews are kept. |
| MINT_QUEUE_FULL | $0.0000 | The extraction service's session queue was full. Early stop; delivered reviews are kept. |
| DEADLINE_EXCEEDED | $0.0000 | The per-request deadline was hit. Returned as an unbilled row with status_code 504. |
| ACTOR_DEADLINE_NEAR | $0.0000 | The run approached its time limit and stopped cleanly after the reviews already delivered. |
| NO_INPUT | $0.0000 | No usable location URL or ID was provided. |
How to handle these in a pipeline
Branch once on success, then switch on code for the misses. Input-shaped codes (VALIDATION_FAILED, not-found codes) are permanent for that input — retrying them re-buys the same answer. Time-shaped codes (DEADLINE_EXCEEDED, the timeout codes) can succeed on a later attempt. Include the request_idwhen you open an issue on an actor's Apify page and we can trace the exact request. Worked examples with error branching are in the Python guide and the n8n guide.