Errors
URLpipe uses conventional HTTP status codes and a consistent JSON error shape, so failures are easy to detect and handle.
Status codes
200 OK401 Unauthorized403 Forbidden422 Unprocessable Entity429 Too Many RequestsError shape
When an operation fails, the response is JSON with a single error field holding a human-readable message:
{
"error": "The request timed out."
}Three responses carry extra fields: the quota 429 (with limit, used, needed, resets_at), the parallel-requests 429 (with limit and running), and the invalid-parameter 422 shown below. Both 429s also carry next_plan and upgrade_url: the plan that lifts the limit and where to switch to it.
Authentication errors
A 401 Unauthorized means the Authorization header is missing or the token doesn't match an active project key; its code is invalid_api_key, and the message says which of the two it was. A 403 Forbidden with the code email_unverified means the key is fine but none of the organization's admins has confirmed their email address yet — resending the key or rotating it will not help; an admin clicking the link we emailed them will. See Authentication.
Validation errors
Bad parameters return a 422 with a machine-readable error code:
- Name
invalid_url- Description
- The
urlis missing or not acceptable. It must be a validhttp/httpsURL for a public domain — not an IP address,localhost, an internal hostname, or a custom (non-default) port. It must not carry credentials:https://user:pass@example.comis rejected.
- Name
invalid_max_age- Description
- The
max_agevalue couldn't be parsed. Use a number of seconds or a duration like"2 hours".
- Name
invalid_options- Description
- A page option or screenshot option is out of range, of the wrong type or not one we know, and the message names which —
"screenshot_options.viewport_width must be a whole number from 320 to 1920.", for example.
- Name
invalid_labels- Description
- labels must be an object of up to 16 keys with string values, and the message names what to change —
"labels.client must be a string.", for example.
- Name
invalid_auth_profile- Description
- The auth_profile is not one of this project's, the URL is on none of its domains, or it was named on
/lighthouseor on a scrape that includeslighthouse— and the message says which.POST /auth_profilesanswers with the same code when the state uploaded is not one it can use.
- Name
invalid_idempotency_key- Description
- The Idempotency-Key must be 1 to 255 printable ASCII characters, with no spaces.
- Name
idempotency_key_reused- Description
- This
Idempotency-Keycame with a different request in the last 24 hours. Nothing ran: send a new key for a new request. See retries & duplicates.
- Name
report_to …- Description
- A
report_towas given that we will not deliver to, and the message names the reason — the same rules the URL being analyzed is held to, so an IP address, alocalhostaddress, credentials in the URL or a custom port are all refused. Omitting it entirely is not an error: see where results go.
Common failure messages
Operational failures — network issues, unreachable or oversized pages — come back as a 422 with one of these messages:
Busy pages are waited out for you
Three of those messages — a timeout, a 5xx and a 429 — mean the page is struggling rather than broken, and they are the ones a retry actually fixes. URLpipe does that part itself: when a page starts stalling, requests to that host are spaced further and further apart and the analysis is tried again, for up to ten minutes, before any failure is reported. A crawl of a site that cannot keep up therefore takes longer and still finishes, instead of failing every request after the first few.
What you see is a request that takes longer, not one that fails. A synchronous request may outlive its wait and answer processing_timeout with a token — collect the result from GET /result/:token as you would for any long analysis. An async request simply delivers later. The processing_time_ms we report covers the whole of it, waiting included.
Recommended handling
- Check the HTTP status first:
401→ fix credentials,403→ confirm the account's email address,429→ back off,422→ inspect the message. - Retry timeouts and connection errors with backoff; they're often transient — and by the time one reaches you we have already waited the page out without success.
- Keep target pages under 10 MB of HTML to avoid
The page is too big to be processed..