Secure Connection Failed

The secure_connection_failed error uses HTTP status 500 and means that the API could not establish a secure HTTPS connection to the target website.

This error is being introduced to distinguish secure connection failures from other network issues. During rollout, these failures may still be reported as network_error. Keep handling both codes in your integration.

{
    "is_successful": false,
    "error_code": "secure_connection_failed",
    "error_message": "The API could not establish a secure HTTPS connection to the target website. Check the website's TLS configuration, or try changing the `url` parameter from `https://` to `http://` if the public page works over HTTP. Do not use HTTP with credentials or sensitive data.",
    "documentation_url": "https://screenshotone.com/docs/errors/secure-connection-failed/"
}

Why this happens

A website can exist and work over http:// while its https:// connection fails. For example, Chrome’s ERR_SSL_VERSION_OR_CIPHER_MISMATCH means that the browser and server cannot agree on a TLS protocol version or cipher.

This happens before the browser can load the page over HTTPS. Ignoring certificate errors does not fix incompatible TLS protocols or ciphers. The ignore_host_errors option only applies to HTTP error responses from a website; it does not fix a failed TLS connection.

How to fix

Check the exact URL

Open the full target URL in a browser, including https:// and the same hostname. Opening a bare domain does not confirm that HTTPS works: the browser may load an HTTP address instead.

If the same HTTPS URL fails in your browser, ask the website owner to fix its TLS configuration. Repeating the same screenshot request is unlikely to fix a persistent TLS configuration problem.

Try the public page over HTTP

If the public page works over HTTP and an unencrypted connection to the website is acceptable, change the target url parameter from https:// to http://:

https://api.screenshotone.com/take?access_key=YOUR_ACCESS_KEY&url=http%3A%2F%2Fexample.com&format=png

Replace example.com with the target website and YOUR_ACCESS_KEY with your access key. Keep the ScreenshotOne API endpoint on HTTPS; only the target url changes. ScreenshotOne does not automatically switch a failed HTTPS request to HTTP.

HTTP does not encrypt the connection to the target website or protect its content from modification in transit. Do not use this workaround for authenticated pages, URLs containing tokens or other secrets, or requests that send credentials through authorization, headers, or cookies. The HTTP page may also differ from the HTTPS page.

If the HTTP address redirects back to the failing HTTPS address, or the browser requires HTTPS through HSTS, this workaround will not help. The website’s HTTPS configuration needs to be fixed.

Showing this error to your users

Explain that a secure connection to the target website could not be established. Suggest checking the exact URL, asking the website owner to fix HTTPS, or explicitly trying HTTP for a public page without credentials or sensitive data. Let the user choose whether HTTP is acceptable; do not automatically replace https:// in every failed request.

See the error-handling example for how to display a message based on error_code.

Reach out to support

If the exact HTTPS URL works in your browser but fails in ScreenshotOne, contact support@screenshotone.com. Share the error code and message, the request time, and the target hostname and path. Remove access keys, URL credentials, tokens, cookies, and sensitive query parameters before sharing request details.