How to Troubleshoot a Screenshot API That Cannot Reach a Website

When a screenshot API cannot reach a website, first inspect the API response status, content type, and error body. Then check the URL and public DNS, determine whether the destination is refusing or blocking the renderer, and adjust navigation waits only if the evidence points to a slow page. A longer timeout cannot fix a malformed URL, failed DNS lookup, or refused connection.

Keep the API request’s HTTP status separate from the target website’s final HTTP status: providers may expose these separately, and their error names and status mappings are provider-specific. The steps below work as a diagnostic sequence; check your provider’s current documentation for its parameter names, limits, and retry rules.

1. Inspect the API response before treating it as an image

A successful capture may return image bytes, while a failed request may return JSON or another error payload. Save the response headers and body, and only open the output as an image after confirming the response indicates success. Do not infer that the target is unreachable solely from a corrupt image file.

Check the endpoint, HTTP method, authentication method, and URL parameter or request body against the provider’s quickstart. If the provider supplies a request ID, retain it. If it separately reports the final target document status, inspect that too. For example, Screenshot API documents image bytes from its screenshot endpoint and a target status in X-Page-Status; a 401 or 403 there can indicate that the capture reached a login or error page instead of the intended content. Those header names and meanings are specific to that service. Screenshot API documentation

curl -sS -D response-headers.txt \
  -o response-body \
  -G 'YOUR_SCREENSHOT_API_ENDPOINT' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --data-urlencode 'url=https://example.com'

Replace the endpoint and authentication syntax with the values documented by your provider. Inspect response-headers.txt for the HTTP status and content type. If the body is JSON, read its exact error code and message instead of opening it as an image. Do not share an unredacted key or authorization header in a support ticket.

2. Verify URL syntax, scheme, and DNS

Make sure the target is a complete HTTP or HTTPS URL with the intended hostname and path. Check for a typo, missing scheme, unexpected port, URL-encoded characters, or credentials embedded in the URL. Screenshot APIs commonly restrict schemes and may reject embedded credentials, unsupported ports, private addresses, reserved ranges, or hostnames that resolve to those ranges; the exact rules vary by service.

Next, check whether the hostname resolves publicly. A newly published site may not have propagated through DNS yet. A provider-specific name_not_resolved error points toward a hostname lookup problem; it is not a universal error label. Compare resolution from your environment with the provider’s diagnostics if available, and confirm that the hostname has a public address.

A hosted renderer normally cannot reach a site that exists only on localhost, a company intranet, or a private IP. Do not expose private content casually to make a capture work. Coordinate with the site owner and use an access design appropriate to the content before making it publicly reachable.

3. Identify which connection stage failed

Use the provider’s exact error code as a clue, then verify the corresponding stage. Labels and status-code mappings differ between APIs, so preserve the provider name and the exact code when searching documentation or contacting support.

Observed result	Likely area to inspect	Next check
Name resolution error, such as `name_not_resolved`	Hostname or DNS	Check spelling, public DNS records, and propagation for a newly published hostname.
Connection error, such as `network_error` or `ERR_CONNECTION_REFUSED`	Destination access, routing, or service availability	Check whether the site accepts connections from a hosted renderer and whether the origin is up.
TLS or tunnel error	HTTPS configuration or network path	Verify the certificate, hostname match, and provider-specific network restrictions.
Host returned an HTTP error or target status is 401/403	Destination response, login, or automated-visitor policy	Confirm the URL and access requirements; determine whether the target intentionally denies automated access.
Timeout	Navigation, rendering, or a page that does not reach the selected wait condition	Confirm basic reachability first, then adjust wait behavior and supported timeout limits.
Temporary unavailable or service error	Screenshot provider capacity or transient failure	Wait briefly and retry according to the provider’s policy; avoid rapid retry loops.

ScreenshotOne documents examples including name_not_resolved, network_error, host_returned_error, timeout_error, and temporary_unavailable. ScreenshotAPI documents a different set of network and browser error labels. These examples illustrate why the actual provider’s error definitions matter; they are not standardized industry-wide codes. ScreenshotOne error documentation · ScreenshotAPI documentation

4. Check destination access and regional differences

If the site opens from your computer but not from the screenshot service, the two requests may take different network paths. The site may block automated browser traffic, unfamiliar IP ranges, or traffic from particular regions; it may also require an authentication flow that the capture request does not perform. A provider’s network_error can mean the target blocked the renderer or was temporarily unavailable, so confirm the origin’s behavior rather than guessing.

Ask the site owner or API provider to confirm permitted access when necessary. Automated access must comply with the target site’s rules. A proxy retry is a later diagnostic only when evidence suggests IP throttling, regional routing, or a restriction limited to the provider’s default IP range, and only when the target permits automated access. ScreenshotOne’s timeout guidance explicitly says, “A proxy is not the first fix for timeout_error.” ScreenshotOne timeout guidance

5. Adjust waits and timeouts only for slow renders

Once URL, DNS, and access checks pass, investigate a timeout. A page may be slow, fail to emit DOMContentLoaded, or keep loading resources so that a network-idle condition never arrives. A configured post-load delay can also consume the available time. Try a less demanding navigation wait condition, remove unnecessary delay, or raise the timeout within the provider’s documented limits.

Browser rendering services may offer waits such as load, domcontentloaded, or network idle. The right choice depends on the page and service. A page with long polling or continuously loading resources may never become network-idle, while a page that builds content after DOM readiness may need a selector wait or a modest delay. Do not copy timeout values from another provider’s examples as universal defaults. Cloudflare Browser Rendering documentation

Change one setting at a time and record the resulting error and target status. Increasing the timeout will not repair failed DNS, invalid URL syntax, a refused connection, or a deliberate access denial.

6. Retry temporary failures and escalate with useful evidence

For an explicitly temporary service failure, wait briefly and retry according to the provider’s documented policy. Avoid aggressive loops, especially after a rate-limit response. If the issue persists, send the provider a minimal reproducible request and these details:

Provider, endpoint, HTTP method, and relevant non-secret options.
Target URL and UTC timestamp of the attempt.
API response status, content type, exact error code and message.
Target status, if the API exposes it, and request ID, if available.
Whether the site resolves publicly and whether it opens from another network.

Redact API keys, cookies, passwords, authorization headers, and other secrets. Do not include private page content unless the provider has an approved way to receive it.

7. Troubleshooting checklist

The downloaded file is not a valid image: inspect the HTTP status, content type, and response body; it may be an error payload.
The URL works locally but not through the API: verify public DNS and check for private-address restrictions, IP-based blocking, regional routing, or required login.
The target status is 401 or 403: the destination may be showing a login/error page or denying the renderer; confirm the target’s access policy.
The request times out: first confirm DNS and destination access; then reduce excess delay, choose a suitable wait condition, and adjust the timeout within documented limits.
Only a newly deployed hostname fails: check public DNS records and allow for propagation before retrying.
Failures are intermittent and explicitly temporary: apply the provider’s retry guidance with bounded attempts and backoff; check for rate limiting.
Repeated errors remain unexplained: collect the exact request, UTC time, response details, target status, and request ID, then contact provider support with secrets removed.

8. Reliability and cost considerations

Keep retries bounded and error-aware. Retrying a temporary renderer failure may help; repeating a malformed URL or a denied destination usually will not. Use the provider’s rate-limit and retry guidance, and avoid turning a transient problem into a burst of duplicate capture requests.

Capture services differ in how they treat failed navigations, target HTTP errors, cache hits, and billing. Check the service’s current pricing and response metadata instead of assuming every failed attempt is free or billable. Preserve the API status and target status independently in logs so that later analysis can distinguish a provider request failure from a captured destination error.

9. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. Its capture flow accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers say which outcome occurred. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`ScreenshotNeo returned HTTP ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', image));

For every API request, inspect its HTTP result before assuming the response is an image. ScreenshotNeo provides full-page captures with lazy images loaded, CSS-selector element captures, dark mode, device presets and custom viewports, retina scale, PDF settings, custom CSS and JavaScript, selector clicks and waits, request blocking, headers, cookies, user agent and authorization, timezone and geolocation, transparent backgrounds, resizing, configurable caching, signed public image links, async jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. Parameter names used by other screenshot APIs also work to make switching easier.

ScreenshotNeo offers 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000 screenshots. The other plans are Growth at $15 for 15,000, Pro at $39 for 60,000, Scale at $99 for 250,000, and Business at $249 for 1,000,000; yearly billing gives two months free. Every feature is available on every plan. Start free with 1,000 screenshots a month and no card.

FAQ

Does a successful API HTTP status prove the target page loaded correctly?

No. A provider may return a successful API response containing a capture of a target login or error page. Check any separately reported target status and inspect the captured result.

Should I use a proxy whenever the API cannot reach a site?

No. First establish that the URL, DNS, destination access, and render timing are valid. Consider a proxy only when evidence points to IP or regional routing and the target permits automated access.

Can a public screenshot API capture my localhost site?

Not while it is reachable only from your machine. A hosted renderer must be able to reach the target, and providers may reject private or reserved addresses.

Are screenshot API error codes interchangeable?

No. Use the provider’s own documentation for the exact label and status mapping, and include that provider name when escalating.