How to Fix Certificate or SSL Errors From a Screenshot API

Certificate errors in a screenshot workflow can happen on either of two HTTPS connections: your client connecting to the screenshot API, or the API’s rendering browser connecting to the page you want to capture. First check whether you received an API response. If the client could not establish HTTPS to the API, investigate your runtime, proxy, clock, and CA trust. If the API accepted the request, inspect its response and render diagnostics to determine whether navigation to the target failed. Keep certificate verification enabled; fix the certificate or trust configuration instead of bypassing validation.

1. Identify which TLS connection failed

A screenshot request commonly involves two independent TLS handshakes:

Caller → screenshot API: your code validates the API endpoint’s certificate. A failure here usually means no normal HTTP response was received.
Screenshot browser → target site: the rendering browser validates the website certificate. The API may accept the request and then return an error, navigation status, or a captured browser error page, depending on the provider.

Record the exact error, API HTTP status, response headers, content type, runtime and browser versions, and target URL (redact credentials and tokens). A non-200 status or invalid image alone does not prove a TLS failure. Some APIs return JSON errors rather than image bytes; check status and content type before saving a response as an image. Provider diagnostics vary, so use the provider’s render logs and target-page status fields where available. See the [Screenshot API documentation on response status](https://screenshotapi.net/documentation) and [ScreenshotEngine’s response guidance](https://screenshotengine.com/docs).

Observation	Likely location	First checks
Client reports a TLS/certificate exception before receiving HTTP status	Client → API	Proxy interception, runtime CA bundle, system clock, endpoint hostname and trust store
API returns an HTTP response, but render failed or the output is an error page	Renderer → target	Target hostname, certificate dates and chain, renderer logs, target-page status
Target requires a client certificate	Renderer → target authentication	Confirm mTLS is required and whether the screenshot provider supports client certificates

2. Capture the response safely

Use this Python example to preserve response metadata and avoid mistaking a JSON error for an image. Replace the endpoint and authentication according to your provider’s documentation. Do not print secrets into shared logs.

import requests

api_url = "https://YOUR-SCREENSHOT-API-ENDPOINT"
params = {"url": "https://example.com"}

try:
    response = requests.get(api_url, params=params, timeout=90)
    print("HTTP:", response.status_code)
    print("Content-Type:", response.headers.get("content-type"))
    print("Body preview:", response.text[:1000] if "json" in response.headers.get("content-type", "") else "binary response")
    response.raise_for_status()

    content_type = response.headers.get("content-type", "")
    if not content_type.startswith("image/"):
        raise RuntimeError(f"Expected an image, received {content_type or 'unknown content type'}")

    with open("shot.png", "wb") as output:
        output.write(response.content)
except requests.exceptions.SSLError as exc:
    print("TLS failed before a normal API response:", exc)
except requests.exceptions.RequestException as exc:
    print("Request failed:", exc)

This example intentionally does not set verify=False. If an exception occurs before status is printed, investigate client-to-API TLS. If status prints and the response is JSON or an error page, investigate the provider’s rendering result and target navigation.

3. Fix client-to-API certificate failures

Check the API hostname and system time. Use the documented HTTPS hostname exactly. A wrong hostname can fail identity validation; an incorrect local clock can make a valid certificate appear expired or not yet valid.
Inspect proxy settings. Corporate proxies sometimes intercept TLS and substitute a certificate signed by an organization’s private CA. If your runtime does not trust that CA, configure the approved root certificate in the runtime’s trust configuration.
Update the CA bundle or trust store. Use your operating system or runtime’s supported certificate bundle mechanism. Confirm that the certificate chain presented to your client terminates at a trusted root.
Reproduce outside the application. From the same machine and network, make a request to the API endpoint with a command-line HTTP client. If it fails only in one runtime, compare that runtime’s CA configuration and proxy environment.

For a specific Playwright browser-installation scenario, its documentation says an intercepting proxy with an untrusted custom CA can cause self signed certificate in certificate chain while downloading browsers. It instructs users to set NODE_EXTRA_CA_CERTS before installing browsers. This applies to that Node/Playwright setup; it is not a universal setting for hosted screenshot APIs. See [Playwright’s proxy and firewall guidance](https://playwright.dev/docs/browsers#install-behind-a-firewall-or-a-proxy).

# Set this before installing Playwright browsers in the documented Node scenario.
export NODE_EXTRA_CA_CERTS=/path/to/organization-root-ca.pem
npx playwright install

Use your organization’s verified CA file and follow its handling rules. Do not download a purported root certificate from an untrusted source.

4. Fix target-page certificate failures

If the API accepted the request, examine the target from the renderer’s point of view. The key checks are:

Hostname identity: the requested host must match a name in the server certificate. Chrome identifies errors such as NET::ERR_CERT_AUTHORITY_INVALID and ERR_CERT_COMMON_NAME_INVALID among certificate errors. See [Chrome Help: Fix connection errors](https://support.google.com/chrome/answer/6098869).
Validity period: confirm the certificate is currently valid and the issuing chain has not expired.
Complete trusted chain: the server should present the required intermediate certificates, and the renderer must trust the chain’s root.
Redirect destinations: inspect every hostname in the redirect path; a valid certificate on the initial domain does not establish that a redirected host is valid.
Provider logs/status: use navigation diagnostics, target status, and captured error details exposed by the screenshot provider. A screenshot can depict a browser error page without the API itself having a certificate problem.

The exact target cannot be diagnosed without its hostname and the provider’s render output. If the page opens on your workstation but fails in a hosted renderer, compare the certificate chain and network path from those environments rather than assuming they share the same trust store.

5. Treat mutual TLS as a separate requirement

Mutual TLS (mTLS) means the server asks the client to present a certificate. Trusting the website’s server certificate and presenting a client certificate are different steps. First confirm from the site owner or server configuration that the target actually requires client authentication. Then verify whether the screenshot service supports sending a client certificate; a hosted service may not expose that capability.

For a browser you control, Playwright supports origin-specific client certificate configuration using PEM or PFX material. Consult the [Playwright BrowserContext API](https://playwright.dev/docs/api/class-browser#browser-context-options-client-certificates) for the supported configuration and fields. Do not assume this local-browser capability is available in an unrelated hosted screenshot API.

6. Common errors and fixes

Error or symptom	Common cause	What to do
`self signed certificate in certificate chain`	An untrusted CA, often from TLS interception by a proxy	Determine which connection reports it. Add the trusted organization CA to the relevant client/browser trust configuration. For Playwright browser downloads, follow its `NODE_EXTRA_CA_CERTS` guidance.
`NET::ERR_CERT_AUTHORITY_INVALID`	The presented chain is not trusted by the validating client or renderer	Check the chain and intermediates; install the approved CA where you control the client, or have the target administrator repair the chain.
`ERR_CERT_COMMON_NAME_INVALID`	The URL hostname does not match certificate identities, or a proxy presents a certificate for another host	Use the canonical hostname and correct the target certificate or proxy configuration.
API returns JSON where image bytes were expected	Request/authentication error or render failure response	Inspect HTTP status, content type, and error body before saving or decoding as an image.
Browser shows “Your connection is not private”	Certificate identity, validity, chain, local proxy, captive portal, or extension issue	For local Chrome, sign in to any Wi-Fi portal and try Incognito or disable extensions as Chrome Help suggests. These checks may not apply to a remote renderer.
Works locally, fails through hosted capture	Different network, trust store, proxy, or renderer configuration	Use provider logs and ask whether target certificate diagnostics or custom trust roots are supported.

7. Retest with verification enabled

Keep TLS certificate verification on in the client and browser.
Retry the API call and record status, content type, and provider diagnostics.
Confirm the saved output is actually the requested screenshot rather than a browser error page.
Retest after a certificate renewal, trust-store change, proxy change, or target configuration fix.

Avoid verify=False, disabling browser certificate checks, or flags such as --ignore-certificate-errors as routine fixes. They remove protection against an impostor endpoint or intercepted connection. If a local-only diagnostic temporarily requires a bypass to isolate a cause, do not ship that setting or capture sensitive pages with it; restore verification and repair trust.

8. Performance, reliability, and cost considerations

Retries: a certificate validation error is generally configuration-related, so repeated retries usually reproduce it. Retry only after confirming a transient network issue or after changing the certificate/trust path.
Timeouts: a timeout is not itself proof of a certificate problem. Record whether TLS negotiation completed and distinguish connection timeouts from render/navigation timeouts.
Reliability: keep the original exception, status, headers, and redacted URL in diagnostics. Avoid logging API keys, cookies, authorization headers, or full sensitive URLs.
Cost: check your provider’s billing rules for failed navigation and retries. Do not assume a failed capture is free; billing behavior differs by provider.
Security: private CA files and client certificates are credentials. Restrict access and do not paste them into bug reports.

9. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. If the issue is with your own caller’s TLS trust, switching APIs will not repair that client-to-API connection; this option avoids managing a browser for captures when the API connection works. 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}`);

Cookie and consent banners, newsletter popups, and chat widgets are removed before capture; each cleanup step can be turned off.
Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are never billed. Responses include X-Page-Verdict and X-Billed headers.
An MCP server lets Claude, Cursor, and other MCP clients use take_screenshot, get_page_info, and capture_pdf.
1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000 screenshots. Every feature is on every plan.

10. FAQ

Does an SSL error mean the screenshot API is down?

No. The TLS failure may be between your client and API, or between the renderer and the target. Determine whether an HTTP response was received and inspect render diagnostics.

Can I ignore certificate errors just for screenshots?

That weakens validation and can expose the connection to interception. Correct the certificate or trust setup and leave verification enabled.

Can I capture a site that uses a private certificate authority?

Only if the validating client or rendering environment trusts that CA and the screenshot provider supports the needed trust configuration. Confirm provider capabilities before relying on a private-CA target.

Why does the same URL work in my browser but fail in the API?

Your browser and the provider’s renderer can use different networks, proxies, certificate stores, and client authentication. Compare diagnostics from the environment that actually performs the failing handshake.