Skip to main content
Every ZapFetch error follows a consistent envelope so your error-handling code stays simple regardless of which endpoint triggered the failure. The HTTP status code is the primary signal; the error field disambiguates between distinct failure modes that share a status. 
{
  "success": false,
  "error": "short_machine_readable_code",
  "message": "Human-readable explanation of what went wrong."
}

​
401 — Unauthorized

{ "success": false, "error": "unauthorized", "message": "Invalid API key." }
Cause: The Authorization: Bearer <ZapFetch API key> header is missing, malformed, or references a key that does not exist or has been revoked. Fix:
  • Confirm the key is the UUID-style ZapFetch key copied from Dashboard → API keys (not a Firecrawl Cloud key).
  • Check that the key has not been revoked in Dashboard → API keys.
  • Make sure you are sending requests to api.zapfetch.com and not a stale hostname.

​
402 — Payment Required

{
  "success": false,
  "error": "insufficient_credits",
  "message": "Your credit balance is 0. Upgrade or top up."
}
Cause: Your plan’s monthly credits are exhausted. Fix: Top up or upgrade from the Billing page. In-flight crawls that were already charged against your credits will still complete their dispatched pages; new requests are blocked until you replenish your balance.

​
404 — Not Found

{ "success": false, "error": "not_found", "message": "Crawl job abc123 not found." }
Cause: The requested resource — such as a crawl job — does not exist on your account, or has been garbage-collected. Crawl results are retained for 30 days. Fix: Confirm the ID and that you are using the correct API key for the owning account. If the results have expired, re-run the crawl.

​
429 — Too Many Requests

{
  "success": false,
  "error": "rate_limited",
  "message": "You have exceeded 50 requests/second for the Starter plan."
}
Cause: Your API key has exceeded the per-plan request rate. See Rate limits for per-plan limits, the full 429 response shape, and recommended backoff strategies. Always honor the Retry-After response header.

​
500 — Internal Server Error

{ "success": false, "error": "internal_error", "message": "Unexpected failure. Please retry." }
Cause: A ZapFetch-side issue, or a transient upstream failure while fetching the target page. Fix:
  • Retry once with backoff — most 500s are transient.
  • If the error persists for a specific URL, the target site may be actively blocking scrapers. Try enabling stealth mode or alternate user agents on the request.
  • If an entire endpoint is consistently failing, check status.zapfetch.com and file a report.

​
Debugging tips

  • Log the full response envelope. The error and message fields almost always identify the exact problem. Treating every failure as a generic network error hides the real cause.
  • Reproduce with curl first. If curl fails, the issue is on the backend or with your API key. If only your SDK fails, the problem is a client-side integration issue.
  • Check the Console’s Usage page. A sudden drop in successful calls usually points to a credit exhaustion or rate-limit issue rather than an outright bug.