Error codes

Every failure is JSON with an error.code. The code is the contract, the message tells you what to change. A 400 also names the parameter in error.field, and so does a 422. You are never charged for a 4xx or a 5xx.

Every response, good or bad, carries X-Request-Id. Quote it if you write to support. Looking for a fix by symptom instead? See Troubleshooting.

The body

{
  "error": {
    "code": "bad_parameter",
    "field": "timeout",
    "message": "timeout must be a whole number of seconds, 1 to 90. The default is 60. Seconds, not milliseconds.",
    "report_url": "https://app.megalania.io/report#rid=0199f0a2-7c1e-7000-8000-000000000001"
  }
}

field is present on a 400, on a 422 convert_cap or unsupported_content, and on a 503 unavailable when one parameter is the cause. code, message and report_url are always there.

report_url opens the dashboard’s “Report a problem” page with this request id filled in. The id is the only thing in it, after the #. Open it, add a short note, and send.

The table

none and refunded both cost 0 credits. refunded means we held the credits while the request ran and gave them back.

Four 400s are worth knowing about:

• An unknown parameter is a 400. We do not ignore it. render=true copied from an old script would otherwise get you a plain fetch, without the JavaScript you asked for. error.field names the key you sent.
• A query string we cannot read has no field. Almost always a url pasted before our parameters. Put url last and paste it as it is, or percent-encode it.
• A JSON value of the wrong type names the key. On POST /v1 every value is a string, headers is a list of strings, and timeout, max_credits and max_age also take a whole JSON number. "timeout": 30.5 is a 400 naming timeout; send "timeout": 30.
• A private address in url is a 400. We only fetch public addresses, so a literal loopback, private, link-local, unique-local, multicast or broadcast address is refused and nothing is charged.
• A header we set for you is a 400. headers cannot set Host, Connection, Content-Length, Transfer-Encoding, TE, Trailer, Upgrade, Expect, Keep-Alive, Via, HTTP2-Settings or any Proxy- header; the message names the header and nothing is charged.

The two ways in

POST /v1 with a JSON object is the canonical call and the one that never needs encoding. GET /v1 with query parameters is the paste-a-URL one, and everything in the next section is about that one only.

method, body and content_type exist only in the JSON envelope. Sending one of them in a query string is a 400 naming it, so a request you meant as a POST is never quietly charged as a GET.

Passing a URL that has its own query string

Paste it. Put our parameters first and url last:

/v1?engine=http&url=https://example.com/catalogue/page-2.html?sort=price&ref=nb

Everything after url= that is not one of our parameter names belongs to the target and reaches it as you sent it. Encoding only the ? is fine too. Two cases need a fully percent-encoded url instead: the target’s own query uses one of our names (engine, timeout, …) or a price word from another vendor (render, premium, country, …), or you want to put our parameters after it. The 400 says so when it happens.

Retry-After

Sent with busy (503), over_concurrency, rate_limited, target_rate_limited and free_failures_spent (429, counting down to 00:00 UTC), monitor_too_soon (409), and unavailable on a batch quote (503). It is a whole number of seconds, from 1 to 86400. Sleep that long, then send the same request again. The other 429s (daily_cost_cap, period_cost_cap, free_tier_cap, llm_token_cap, llm_global_stop) carry no Retry-After: their message names the time the limit resets. Nothing was charged, so a retry costs you nothing extra.

Retrying safely

Send Idempotency-Key: <your own id> on any call you might retry. One to 128 printable ASCII characters; a UUID is the usual choice. It is yours alone: another customer sending the same word does not touch your call. It works on GET /v1, POST /v1 and QUERY /v1.

• The first call with a key runs and is charged as usual.
• Any later call with the same key, inside 24 hours, is a 409 replayed. It charges nothing and carries the X-Request-Id of the first call.
• A replay does not hand you the page again. We keep no bodies, so what a replay tells you is that your first call went through and your client should stop retrying.
• Anything we refund releases the key, so retrying is safe and normal: a 402, a 429, and every 5xx of ours (busy, timeout, fetch_error, internal). Send the same request with the same key. You were not charged for the attempt that failed, and the retry is charged once.
• A 422 convert_cap or upstream_cap is refunded too, so it releases the key. The same request fails the same way. Change response_types, or fetch a smaller page, first.
• A delivered result keeps the key, and so does a 422 blocked. A block is free, but it is an answer, so a second call with that key is a replayed.
• A 503 busy where our credit store did not answer stops before the call runs, so it is never charged, and it releases the key like any other 5xx. If the store is still down when we let go, the key frees itself within a minute. Only if the store took the call’s reserve and then lost its answer can the retry come back 409 replayed for up to 24 hours; nothing was charged then either, so send a new key.
• Send the header once. Two Idempotency-Key headers on one call are a 400 naming Idempotency-Key.
• After 24 hours a key is forgotten. The same key then starts a new request and is charged like one, so a key is not permanent protection.
• Without the header nothing changes, and the call costs no extra time.
• POST /v1/batches and checkout take the header too. A replay there is a 200 with the batch or checkout page the first call made. The same key with a different body is a 422 idempotency_mismatch. A replay that races the first call waits up to 2 seconds for it; if the first call is still not done, the answer is 503 busy with Retry-After: ask again with the same key and body.

200 is not always what you wanted

A target that answers under 500 is a delivered result, whatever it answered. You get HTTP 200 from us and the target’s own status in X-Target-Status. There is no error body to read, so read the headers.

A block is never a 200. When the target blocks us (401, 403, 407, or an anti-bot challenge) on every route we try, the answer is a 422 blocked with X-Billing: blocked, X-Hops, and X-Untried when a route is left. It is free. The one exception is a request with actions above the failure cap: still a 422 blocked, but with X-Billing: failure_cap, and charged.

Blocks we detect are free, however often they happen. Your plan’s usage limit still counts what they cost us, so a key that fails all day stops at that limit with a 429 daily_cost_cap. A target that answers 429 is not a block result: you get our own 429 target_rate_limited (see the table above).

Actions and the failure cap

A request with actions can click, type or submit on the target and then fail on purpose, so free failures there have a cap. We count your requests with actions over a sliding hour, this one included. A request counts as failed when it ends free: action_failed, a block, a timeout or any other error. When at least 20 of them ran and more than 30% failed, an action_failed or a block is charged the page’s price, actions included, and carries X-Billing: failure_cap. Other free errors stay free and only count. It is never charged twice, and bytes above the included data stay free. The count moves on as the hour slides; requests without actions never count. Schema extraction is never charged for a failure: after 20 failed extractions in a UTC day, the account’s next extraction is a free 429 llm_token_cap, before the page is fetched.

A free answer carries no page content, on /v1, map, MCP and in a batch. A block is a free 422 blocked: the headers (X-Billing, X-Block, X-Challenge, X-Vendor, X-Hops, X-Untried, X-Target-Status) say what happened, and the body is only our JSON error. A target 5xx is a free 422 target_error with X-Target-Status, never an empty 200. In a batch, a free item is done with no result_url, and its error says why: blocked, target_error or needs_js.

engine=browser sends the page straight to a real browser (Chrome, on datacenter exits). Add proxy_tier=residential for residential IPs. It pays the browser’s price: 15 credits on datacenter, 32 on residential, and only when the page comes back. Bytes above the included data add a price for each started 128 KiB, up to the byte cap. A browser request reserves that whole worst case from your balance before it runs, not only the floor; with less balance or a lower max_credits, the page is cut at the bytes you can pay for. You pay the actual price. Batches price it the same way. When every browser is busy, the answer is a free 503 busy with Retry-After. When no browser runs at all, it is a free 503 unavailable naming engine.

Money headers

Errors carry no X-Credits-Charged, because nothing was charged.

Safety headers

Result and screenshot download links (batches, monitors) download as a file: they carry Content-Disposition: attachment, so a stored page never opens on our storage host.