Reference

Errors

Errors are not billed. Requests that are refused cost nothing, and requests where every attempt failed cost nothing either, however many retries Siftzo made. The one exception is a failed AI extraction, where the scrape that succeeded is billed.

Two shapes

Refused requests never reach a website. They return only an error object:

402 Payment Required
{
  "error": {
    "code": "credits_exhausted",
    "message": "the monthly credits are used up"
  }
}

Failed requests were attempted but did not produce a result. They return the normal result object with status: "failed", so you can see the tier and number of attempts, plus the same error object. For async jobs this object is the job result, returned with HTTP 200.

In both cases, use error.code in your code; the message is for humans and may change.

Refused before running

Errors for refused requests
HTTPCodeBilledWhenWhat to do
400invalid_requestNoThe body or a parameter is invalid: missing url, unknown field, bad render value, timeout out of range.Read the message, fix the request.
401invalid_api_keyNoThe key is missing, unknown or revoked.Check the X-API-Key or Authorization header.
402credits_exhaustedNoThe request would go over your monthly credit limit, or over the monthly cap of the key's team.Wait for the next month (UTC), raise your spending limit or upgrade. For a team cap, an owner or admin can raise it under Teams.
402llm_tokens_exhaustedNoAI extraction (or the Data API's LLM fallback) would go over the account's monthly LLM token cap.Wait for the next month (UTC), or contact support to raise the cap.
403target_not_allowedNoThe target is a private or internal address, or a domain on Siftzo's blocklist.Siftzo only fetches public websites. See Responsible use.
403account_suspendedNoThe account has been suspended.Contact support.
404not_foundNoUnknown endpoint, a job that does not exist or is older than 24 hours, or a feed or run that is not in your account. Feed run downloads are 404 after 7 days.Check the path and ID.
409feed_limitNoThe account already has 20 feeds.Delete a feed you no longer need.
409run_in_progressNoA feed was asked to run while a run of it is still going.Wait for the run to finish.
429concurrency_limitNoYou already have as many requests running as your plan allows.Wait for a request to finish and retry. Retry-After: 1
429too_soonNoA feed was asked to run less than 15 minutes after its last run started.Wait, or let the schedule run it.
429batch_limitNoYou already have 20 batches that have not finished.Wait for a batch to finish, or cancel one, then retry.
503extraction_unavailableNoAI extraction is briefly not available.Retry later. Requests without extraction are not affected.
503unavailableNoA Siftzo dependency is briefly unavailable.Retry shortly. Retry-After: 2

Failed while running

Errors for failed requests
HTTPCodeBilledWhenWhat to do
424target_blockedNoEvery attempt was blocked by anti-bot protection or rate limiting.Try render: always, another country, or later.
424target_unreachableNoDNS, TLS or connection errors at the target on every attempt.Check the URL. The site may be down.
424proxy_unavailableNoNo proxy exit was available for the request.Retry, or try without country or with a larger country.
424response_too_largeNoThe target's response is larger than 10 MB.Fetch a smaller resource.
424extraction_failedScrape credits onlyThe page was fetched, but the language model's answer did not match the schema, also after one repair, or the model declined.Simplify the schema or make the prompt clearer.
408timeoutNoThe request did not finish within timeout_ms.Raise timeout_ms (up to 90000) or use async.
503overloadedNoThe engine had no capacity to take the request.Retry shortly. Retry-After: 2
500internal_errorNoSomething failed inside Siftzo.Retry. If it persists, contact support with the X-Request-Id.

Target errors are results

When the website answers with a 4xx or 5xx status, that is not an API error. You get 200 with status: "done" and the website's status in target.status_code. Only 2xx, 3xx, 404 and 410 answers are billed; see billing rules.

Retrying

  • Retry 429, 503 and 500 after a short wait. Honour Retry-After when it is set, and back off exponentially if the error repeats.
  • 424 and 408 already include up to 3 attempts by Siftzo. Retrying straight away rarely helps; change the request or try later.
  • Do not retry 400, 401, 402 or 403 without changing something first.

Every response has an X-Request-Id header. Include it when you contact support.