Error Codes

Example message

"Please provide a url query parameter"

Cause

The ?url= parameter was not included in the request.

Fix

Add the target URL as a url query parameter: ?url=https://example.com/page

Example message

"The provided url is not a valid URL"

Cause

The url parameter is malformed or not a fully-qualified URL.

Fix

Ensure the url value starts with https:// and is a valid, percent-encoded URL.

Example message

"The specified template does not exist"

Cause

The templateId in the path does not match any template in the database.

Fix

Verify the template ID. Find the correct UUID in Dashboard → Templates.

Example message

"The template owner does not have an active subscription"

Cause

The account that owns the template has no active or trialing subscription. The 7-day trial may have expired.

Fix

Log in to your dashboard and activate or renew a subscription plan.

Example message

"The domain "example.com" is not in the authorized domain list"

Cause

The hostname of the url parameter has not been registered in the account's domain list.

Fix

Go to Dashboard → Domains and add the domain. Subdomains are automatically covered by the root domain.

Example message

"Page failed to load within timeout: <target url>"

Cause

The target URL took too long to respond or the page has a very slow first paint.

Fix

Check that the target URL is publicly accessible. Consider increasing the waitTimeout setting in your template.

Example message

"Screenshot generation failed: <error detail>"

Cause

An unexpected error occurred in the browser rendering process.

Fix

Try again. If the error persists, contact support with the target URL and template ID.

Example message

"Origin header is required. This endpoint is intended for browser use only."

Cause

The request was made without an Origin header (e.g., from curl or a server-side request).

Fix

Use the Preview API only from browser JavaScript. For server-side use, switch to the OG Screenshot API.

Example message

"The Origin header is not a valid URL"

Cause

The Origin header value could not be parsed as a URL.

Fix

This is typically a browser issue. Ensure you are calling the endpoint from a standard browser fetch() call.

Example message

"Please provide a url query parameter"

Cause

The ?url= parameter was not included in the request.

Fix

Add the target URL as a url query parameter.

Example message

"The provided url is not a valid URL"

Cause

The url parameter is malformed or not a fully-qualified URL.

Fix

Ensure the url value is a valid, percent-encoded URL starting with https://.

Example message

"The provided client key is not valid"

Cause

The client key in the URL path does not match any account.

Fix

Retrieve your current client key from Dashboard → Previews. If you regenerated it, update your code with the new key.

Example message

"The origin "<hostname>" is not in your registered domain list"

Cause

The hostname of the Origin header has not been registered in your domain list.

Fix

Add the domain in Dashboard → Domains. Localhost is always allowed without registration.

Example message

"No active subscription found for this client key"

Cause

The account associated with the client key has no active or trialing subscription.

Fix

Activate or renew a subscription plan in your dashboard.

Example message

"Page failed to load within timeout: <target url>"

Cause

The target URL took too long to respond.

Fix

Check that the URL is publicly accessible.

Example message

"Screenshot generation failed: <error detail>"

Cause

An unexpected error occurred in the browser rendering process.

Fix

Try again. Contact support if the problem persists.