Read a page problems

Each entry gives the symptom, the cause and the fix, keyed by the status and error in the response. The full contract is in the fetch reference; the guide is Read a web page.

Fetch errors have their own shape: error is a string, not an object. Code written for the other abilities' {"error": {"code": ...}} shape will miss it:

{ "error": "upgrade_required", "message": "web_fetch is a paid capability; upgrade or clear a charge" }

400 social_blocked#

Cause. The URL is on a major social network. Those sites cannot be read, with or without render.

Fix. There is no workaround through Flux. Use the site's own API, or a page that quotes the post.

400 blocked target: ...#

Cause. The URL points at a private, loopback, link-local or cloud metadata address, or a name that resolves to one. Reads only reach the public internet.

Fix. Use a public http or https URL. To read something on your own network, fetch it yourself and pass the text to the model.

400 url required or body must be JSON#

Fix. Send a JSON body with a non-empty url, and Content-Type: application/json.

402 upgrade_required#

Symptom. Every read answers 402 with error: "upgrade_required". From your agent, web_fetch answers payment_required with an upgrade link.

Cause. Page reading is a paid ability, and this key's plan is not paid and cleared yet. Nothing was charged.

Fix. Upgrade in Billing. See Plans.

402 credit_unresolved, or another 402#

Cause. Your credit balance could not be checked, or your balance or a spend cap stopped the read. Nothing was charged.

Fix. Retry credit_unresolved after a short wait. For the others, add credit or raise the cap; see Spend caps.

The Markdown is empty or missing most of the page#

Cause. The page builds itself with JavaScript, so a plain read sees an empty shell. Or the page needs a sign-in, and reads see what a signed-out visitor sees.

Fix. Send "render": true from your code, which renders the page in a browser first. A rendered read costs more. The web_fetch tool cannot render, so call the API for these pages. Pages behind a sign-in cannot be read.

503 capability_unavailable#

Cause. Rendering is unavailable for a while. Nothing was charged.

Fix. Retry later, or drop render if a plain read is enough.

502 provider failed: ...#

Cause. The site failed, returned an error, or took longer than 25 seconds. Nothing was charged.

Fix. Check the URL loads in a browser, then retry.

I read the same page twice and got the old version#

Cause. A read of the same URL within 6 hours comes from the cache. Cached reads are free.

Fix. Wait for the cache to expire, or add a harmless query string to the URL to read it fresh.

404 on every read#

Cause. Page reading is not switched on for this account.

Fix. Contact support.

Still stuck#

See the whole-API Errors page, or ask support.