| name | apify-common-errors |
| description | Diagnose and fix common Apify Actor and API errors.
Use when an Apify run fails, an API call returns 401/403/404/413/429,
a proxy connection drops, an Actor build breaks, or a scrape hits an
anti-bot block, and you need the cause plus a copy-paste fix.
Trigger with "apify error", "fix apify", "actor failed",
"apify not working", "debug apify", "apify 429".
|
| allowed-tools | Bash(curl:*), Bash(apify:*), Bash(npm:*) |
| version | 1.5.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","scraping","automation","apify"] |
| compatibility | Designed for Claude Code |
Apify Common Errors
Overview
Quick diagnostic reference for the most common Apify errors. Covers Actor run
failures, API errors, proxy problems, anti-bot blocks, and platform-specific
issues. The full per-error catalog — raw signature, cause, diagnosis, and
copy-paste fix for all ten errors — lives in
references/error-reference.md; this file is the
lean triage path that points you there.
Prerequisites
- An Apify API token exported as
APIFY_TOKEN (Console > Settings > Integrations).
- Access to the Apify Console for reading run and build logs.
curl and jq on PATH for the diagnostic commands below; apify CLI optional for build inspection.
Instructions
Work the failure from signal to fix:
- Capture the exact error. Grab the
Status / StatusMessage from the
run, or the ApifyApiError message and HTTP code from the API response.
The raw string is the key you match on.
- Match the signature. Find the matching entry in the table below, then
open references/error-reference.md at that
number for the cause, diagnosis, and fix.
- Diagnose before changing code. For run failures, pull the log via the
API or Console (see the FAILED entry). For auth/rate/payload errors, the
HTTP code already tells you the class — see Error Handling.
- Apply the fix from the reference, re-run, and confirm with the
diagnostic commands.
Error signature → reference
| # | Error | Signature to match |
|---|
| 1 | Actor run FAILED | Status: FAILED / exited with code 1 |
| 2 | Actor run TIMED-OUT | Actor timed out after N seconds |
| 3 | Rate limited | Rate limit exceeded (429) |
| 4 | Unauthorized | Authentication required (401) |
| 5 | Build failed | Build failed: npm ERR! |
