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:
{
"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
| HTTP | Code | Billed | When | What to do |
|---|---|---|---|---|
| 400 | invalid_request | No | The body or a parameter is invalid: missing url, unknown field, bad render value, timeout out of range. | Read the message, fix the request. |
| 401 | invalid_api_key | No | The key is missing, unknown or revoked. | Check the X-API-Key or Authorization header. |
| 402 | credits_exhausted | No | The 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. |
| 402 | llm_tokens_exhausted | No | AI 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. |
| 403 | target_not_allowed | No | The target is a private or internal address, or a domain on Siftzo's blocklist. | Siftzo only fetches public websites. See Responsible use. |
| 403 | account_suspended | No | The account has been suspended. | Contact support. |
| 404 | not_found | No | Unknown 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. |
| 409 | feed_limit | No | The account already has 20 feeds. | Delete a feed you no longer need. |
| 409 | run_in_progress | No | A feed was asked to run while a run of it is still going. | Wait for the run to finish. |
| 429 | concurrency_limit | No | You already have as many requests running as your plan allows. | Wait for a request to finish and retry. Retry-After: 1 |
| 429 | too_soon | No | A feed was asked to run less than 15 minutes after its last run started. | Wait, or let the schedule run it. |
| 429 | batch_limit | No | You already have 20 batches that have not finished. | Wait for a batch to finish, or cancel one, then retry. |
| 503 | extraction_unavailable | No | AI extraction is briefly not available. | Retry later. Requests without extraction are not affected. |
| 503 | unavailable | No | A Siftzo dependency is briefly unavailable. | Retry shortly. Retry-After: 2 |
Failed while running
| HTTP | Code | Billed | When | What to do |
|---|---|---|---|---|
| 424 | target_blocked | No | Every attempt was blocked by anti-bot protection or rate limiting. | Try render: always, another country, or later. |
| 424 | target_unreachable | No | DNS, TLS or connection errors at the target on every attempt. | Check the URL. The site may be down. |
| 424 | proxy_unavailable | No | No proxy exit was available for the request. | Retry, or try without country or with a larger country. |
| 424 | response_too_large | No | The target's response is larger than 10 MB. | Fetch a smaller resource. |
| 424 | extraction_failed | Scrape credits only | The 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. |
| 408 | timeout | No | The request did not finish within timeout_ms. | Raise timeout_ms (up to 90000) or use async. |
| 503 | overloaded | No | The engine had no capacity to take the request. | Retry shortly. Retry-After: 2 |
| 500 | internal_error | No | Something 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,503and500after a short wait. HonourRetry-Afterwhen it is set, and back off exponentially if the error repeats. 424and408already include up to 3 attempts by Siftzo. Retrying straight away rarely helps; change the request or try later.- Do not retry
400,401,402or403without changing something first.
Every response has an X-Request-Id header. Include it when you contact support.