Every code these endpoints answer with, by status. One with no endpoint named can come from any of them. An address that fails inside a crawl, or a result page inside a search, carries the same codes in its own entry and does not fail the call.
invalid_json 400 · invalid_request_error- The body is not a JSON object.
unexpected_field 400 · invalid_request_error- The body has a field this endpoint does not take.
web_network 400 · invalid_request_error · search, answer, fetch, extract, map, crawl, jobs, task- network is not web or tor.
web_url_blocked 400 · invalid_request_error · fetch, extract, map, crawl, browser, jobs, task- Not a public http or https address on a standard port; the message says which rule.
web_query 400 · invalid_request_error · search, answer- The query is empty or longer than 300 characters.
web_domains 400 · invalid_request_error · search, answer- includeDomains or excludeDomains is not a list of up to ten website names in lower case, or one name is in both.
web_highlights 400 · invalid_request_error · search- highlights is not true, false or an object with count (1 to 5) and maxChars (100 to 1,000).
web_source 400 · invalid_request_error · search, answer- source is not provider, index or both, or it was given with scope onion.
web_scope 400 · invalid_request_error · search, answer- scope is not web or onion, or it is onion without network tor.
web_contents 400 · invalid_request_error · search- contents is not true, false or an object with format and maxChars.
web_task 400 · invalid_request_error · task- task is missing, empty or over 2,000 characters.
web_steps 400 · invalid_request_error · task- maxSteps is not a whole number from 1 to 30.
web_task_session 400 · invalid_request_error · task- session is not the id of a browser session.
web_limit 400 · invalid_request_error · search, answer, map, crawl, jobs- limit is not a whole number in the endpoint’s range.
web_format 400 · invalid_request_error · search, fetch, crawl, jobs- format is not text or markdown.
web_max_chars 400 · invalid_request_error · search, fetch, crawl, jobs- maxChars is not a whole number in the endpoint’s range.
web_offset 400 · invalid_request_error · fetch, extract, jobs- offset is not a whole number of zero or more.
web_render 400 · invalid_request_error · fetch, extract, crawl, jobs- render is not auto, always or never; a crawl takes auto or never.
web_schema 400 · invalid_request_error · extract, jobs, task- schema is not a JSON Schema this endpoint reads, or neither schema nor prompt was given. The message names the part that is wrong.
web_prompt 400 · invalid_request_error · extract, jobs- prompt is not 1 to 2,000 characters.
job_input 400 · invalid_request_error · jobs- A field of a job call has a value it does not take: an unknown action or kind, urls that is not a list of 1 to 1,000 addresses, keep or keepMinutes out of range, count over 100, or a job that was given neither a webhook nor keep. The message says which.
job_webhook 400 · invalid_request_error · jobs- webhook is not {url}, or its url is not a public https address or an onion address.
web_screenshot 400 · invalid_request_error · fetch- screenshot is not true or false, or it is true with render never.
web_depth 400 · invalid_request_error · crawl, jobs- maxDepth is not a whole number from 0 to 5.
web_patterns 400 · invalid_request_error · crawl, jobs- include or exclude is not a list of up to ten paths that start with /.
web_stream 400 · invalid_request_error · crawl- stream is not true or false.
browser_input 400 · invalid_request_error · browser- An unknown action, or a clientId, network, text, key or direction the action does not take; the message says which.
invalid_api_key 401 · authentication_error- The key is missing, malformed, unknown or revoked.
key_budget_exceeded 402 · invalid_request_error- The key’s monthly budget cannot cover what this call could cost. Raise the budget, or wait for the next month. Nothing was done.
web_balance_required 402 · invalid_request_error · crawl, jobs, browser, task- The account’s balance does not cover a crawl of this many pages, and without one a crawl reads ten pages at most; or a long job was started without a balance; or an address to connect to or watch a browser session was asked for without a balance that covers the session; or a browser task of more than five steps was asked for without a balance. Add credits, or lower limit or maxSteps.
account_paused 403 · permission_error- The account is paused.
origin_denied 403 · permission_error- A page on another website sent the request from a browser. Call these endpoints from your server.
onion_blocked 403 · permission_error · fetch, extract, map, crawl, browser- The onion address is on a published blocklist of services found serving child sexual abuse material. Retrying will not change it.
web_robots_disallowed 403 · permission_error · map, crawl- The website’s robots.txt asks crawlers not to read the address given. Fetch still reads a single page.
browser_session_missing 404 · invalid_request_error · browser, task- The session has ended or belongs to another account. Start a new one.
browser_tab_closed 404 · invalid_request_error · browser- The tab is closed. Read the page for the current tabs.
job_not_found 404 · invalid_request_error · jobs- There is no such job on this account. A job’s record is deleted an hour after it ends, or when its kept results expire.
method_not_allowed 405 · invalid_request_error- The endpoints take POST only.
browser_connect_unsupported 409 · invalid_request_error · browser- This session’s browser cannot be connected to or watched directly: it is a hardened one.
browser_stale_ref 409 · invalid_request_error · browser- The element reference is not from the latest answer, or the page changed. Read the page again.
browser_busy 409 · invalid_request_error · browser- The session is still completing another action.
browser_network 409 · invalid_request_error · browser, task- The action names the network the session does not use. End the session to change network.
job_exists 409 · invalid_request_error · jobs- The same start was received twice; the job is already running.
body_too_large 413 · invalid_request_error- The request body is larger than 12,288 bytes.
model_input_too_long 413 · invalid_request_error · extract, answer- What was given to the model was more than it can read at once, which dense text in some scripts can be. For extract, nothing shorter can be asked for yet: read the page with fetch. For answer, lower limit.
web_too_large 413 · invalid_request_error · fetch, extract, map- A PDF or another document larger than 16 MB, or one that unpacks to more than is read.
json_required 415 · invalid_request_error- The request body is compressed. Send plain JSON.
web_content_type 415 · invalid_request_error · fetch, extract, map- Not a page, text, a PDF or a document that is read (the fetch endpoint lists them), or sent in an encoding that is not read. The message names the older Office formats when the file is one.
web_empty_page 422 · invalid_request_error · fetch, extract, map- No readable text, even when rendered. The page may need a sign-in.
web_pdf_no_text 422 · invalid_request_error · fetch, extract, map- The PDF has no text: it may be a scan.
web_pdf_unreadable 422 · invalid_request_error · fetch, extract, map- The PDF is damaged or protected by a password.
web_file_no_text 422 · invalid_request_error · fetch, extract, map- The document has no text: a presentation of pictures, or an empty file.
web_file_unreadable 422 · invalid_request_error · fetch, extract, map- The document is damaged or protected by a password.
model_refused 422 · invalid_request_error · extract, answer- The model declined to read this content.
web_crawl_offsite 422 · invalid_request_error · crawl- The start address leads to another website; the message names it. Crawl that address.
web_rate_limited 429 · rate_limit_error- The account, or the service as a whole, reached a request limit. The message says which; wait for Retry-After.
web_trial_limit 429 · rate_limit_error- An account without a balance reached a trial limit, or all such accounts reached theirs for the day; the message says which. Add credits for the full limits, or wait for Retry-After.
abuse_limit 429 · rate_limit_error- Too many requests from this network address in a minute.
web_busy 429 · rate_limit_error- Too many calls are running at once: the account’s, the service’s, or other PDFs and documents being read. Retry-After is 2.
render_busy 429 · rate_limit_error · fetch, extract- Only with render always or a screenshot: every renderer is in use.
browser_limit 429 · rate_limit_error · browser, task- The account already has a session with another clientId or network. End it first.
browser_capacity 429 · rate_limit_error · browser, task- Every cloud browser is in use. Retry-After is 60.
browser_viewers 429 · rate_limit_error · browser- The session already has four live views open. Close one first.
browser_tabs 429 · rate_limit_error · browser- The session has five tabs. Close one before opening another.
permission_error 451 · invalid_request_error- The service is not offered where the request comes from.
web_not_found 502 · api_error · search, answer, fetch, extract, map- The website answered 404 or 410.
web_forbidden 502 · api_error · search, answer, fetch, extract, map- The website answered 401 or 403. Through Tor the message adds that it may answer on the regular network.
web_site_busy 502 · api_error · search, answer, fetch, extract, map- The website answered 429: it is limiting requests.
web_http_error 502 · api_error · search, answer, fetch, extract, map- The website answered with another error; the message gives its status.
web_challenge 502 · api_error · fetch, extract- The website asked for proof of a person. This is never attempted.
web_dns_failed 502 · api_error · search, answer, fetch, extract, map- The website’s name does not resolve.
web_redirect_limit 502 · api_error · search, answer, fetch, extract, map- The website redirected more than four times.
web_redirect_insecure 502 · api_error · search, answer, fetch, extract, map- The website redirected an https address to plain http.
web_redirect_invalid 502 · api_error · search, answer, fetch, extract, map- The website sent a redirect with no address to go to.
web_request_failed 502 · api_error · search, answer, fetch, extract, map- The connection failed. Over Tor, retry once.
web_robots_unavailable 502 · api_error · map, crawl- The website’s robots.txt could not be read, so nothing was crawled. Try again later. When it did not answer in time the status is 504.
web_search_failed 502 · api_error · search, answer- The search provider did not complete the request.
extract_failed 502 · api_error · extract- The model did not return data that fits the schema, twice, or the fields were more than it can write in one answer. Nothing is charged.
answer_failed 502 · api_error · answer- The model wrote nothing. Nothing is charged; try again.
web_search_response 502 · api_error · search, answer- The search provider’s answer could not be used.
onion_search_unavailable 502 · api_error · search, answer- The onion index did not answer, or asked for verification.
browser_action_failed 502 · api_error · browser- The action failed; the page may not have loaded. Read it before retrying.
web_unavailable 503 · api_error- The web tools are switched off or the service is not ready. Retry-After is 30.
web_search_unavailable 503 · api_error · search, answer- Regular web search is not configured. Page reads still work.
tor_unavailable 503 · api_error · search, answer, fetch, extract, map, crawl- Tor is down. No direct connection is made in its place.
onion_policy_unavailable 503 · api_error · search, answer, fetch, extract, map, crawl, browser- The onion blocklists could not be refreshed for a day and a half, so onion requests are paused until they can.
index_unavailable 503 · api_error · search, answer- Only with source index: our own index of the regular web cannot be reached, or is still being filled. Search with source provider.
render_unavailable 503 · api_error · fetch, extract- Only with render always or a screenshot: rendering is down. render never still reads the page.
browser_unavailable 503 · api_error · browser, task- Cloud browsers are down or switched off, or the hardened browser was asked for and is not available; a standard session can still be started.
extract_unavailable 503 · api_error · extract, jobs- Field extraction is down or switched off. fetch still reads the page.
answer_unavailable 503 · api_error · answer- Answers are down or switched off. search still returns results.
jobs_unavailable 503 · api_error · jobs- Long jobs are down or switched off. A crawl of up to 100 pages can be streamed instead.
model_unavailable 503 · api_error · extract, answer- The model that reads pages is busy or down. Retry-After says how long to wait.
task_unavailable 503 · api_error · task- Browser tasks are down or switched off. The browser endpoint still works.
browser_connect_unavailable 503 · api_error · browser- Addresses to connect to or watch a session cannot be given out right now. The other actions still work.
model_timeout 504 · api_error · extract, answer- The model took more than a minute and a half to answer.
web_timeout 504 · api_error · search, answer, fetch, extract, map- The website did not answer in time, or a PDF or another document took too long to read. Over Tor, retry once.
web_robots_unavailable 504 · api_error · map, crawl- The website did not answer in time when asked for its robots.txt, so nothing was crawled. Try again: through Tor the first connection to a site is the slow one.
browser_timeout 504 · api_error · browser- The action took longer than 50 seconds and loading was stopped. The session is still open.