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.

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.

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

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.
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 is required
Description
An async request was sent without a valid report_to webhook URL. Async is the default, so this applies to any request that doesn't set sync: true. See Async & sync modes.

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 page is too big to be processed.	The HTML exceeds the 1 MB limit for AI endpoints.

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 1 MB of HTML to avoid The page is too big to be processed..