Errors

URLpipe uses conventional HTTP status codes and a consistent JSON error shape, so failures are easy to detect and handle.

Status codes

Status	Meaning
`200 OK`	The request succeeded. Async requests return 200 with a token.
`401 Unauthorized`	Missing or invalid API key.
`422 Unprocessable Entity`	The operation failed or a parameter was invalid — see the error field.
`429 Too Many Requests`	You've hit your monthly quota for that category of operation.

Error shape

When an operation fails, the response is JSON with a single error field holding a human-readable message:

422 Unprocessable Entity

{
  "error": "The request timed out."
}

Two responses carry extra fields: the quota 429 (with category, limit, used, resets_at), and the invalid-parameter 422 shown below.

Authentication errors

A 401 Unauthorized means the Authorization header is missing or the token doesn't match an active project key. See Authentication.

Validation errors

Bad parameters return a 422 with a machine-readable error code:

Name
invalid_url
Description
The url is missing or not acceptable. It must be a valid http/https URL 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.com is rejected.
Name
invalid_max_age
Description
The max_age value couldn't be parsed. Use a number of seconds or a duration like "2 hours".
Name
report_to …
Description
A report_to was given that we will not deliver to, and the message names the reason — the same rules the URL being analysed is held to, so an IP address, a localhost address, 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:

Message	Cause
The request timed out.	The page took too long to load.
The connection to the server timed out.	A connection to the host could not be established in time.
The requested page was not found.	The host couldn't be resolved, or the page returned HTTP 404.
An internal server error occurred in the requested page.	The page returned an HTTP 5xx status.
The request was invalid.	The page returned another 4xx status (e.g. 401, 403, 410).
There was a problem with the SSL certificate.	The host's TLS certificate could not be validated.
The server refused the connection.	The host actively refused the connection.
Too many redirects occurred while processing the request.	A redirect loop was detected.
No internet connection was detected.	A network connectivity problem occurred.
The request was blocked by the client.	The request was blocked (e.g. by ad-blocking rules).
The requested URL resolved to an address that is not publicly reachable.	The URL, or a redirect from it, pointed at a private or loopback address. Only public web addresses can be analysed.
The requested URL is not a web page.	The URL returned something other than HTML — a PDF, an image or a download, for example.
The page could not be loaded.	The page never came up, so there was nothing to analyse.
An unexpected error occurred while processing the request.	Something failed that we do not have a specific answer for. These are reported to us automatically; retrying is usually worthwhile.
The page is too big to be processed.	The HTML exceeds the 10 MB limit for AI endpoints, or the page holds more content than the AI operation can return in one response.

Recommended handling

Check the HTTP status first: 401 → fix credentials, 429 → back off, 422 → inspect the message.
Retry timeouts and connection errors with backoff; they're often transient.
For AI endpoints, keep target pages under 10 MB of HTML to avoid The page is too big to be processed..

PreviousResponse headers

NextHTML