Direct answer
Certificate errors should be corrected at identity or trust-chain boundaries. Disabling verification converts a visible failure into an interception risk.
What this guide helps you solve
Fix certificate verification, hostname mismatch, expired certificate, and unknown CA errors securely.
Confirm the symptom and blast radius
The TLS handshake fails with certificate verify failed, hostname mismatch, expired certificate, or unknown issuer errors.
A browser or host may work while a container, Node.js process, Python environment, or corporate network fails because trust stores differ.
- Capture the status or exception, response body, request ID, UTC time, client version, and final host before changing configuration.
- Compare one minimal request with the failing workflow to determine whether the issue is global, model-specific, or feature-specific.
- Keep credentials, full prompts, customer data, and private file contents out of screenshots and support bundles.
Common causes and ownership boundaries
Treat the error as evidence from one layer, not as proof that every downstream component failed. These are the highest-value causes to test first.
- The requested hostname is not covered by the certificate SAN.
- The leaf certificate is expired, not yet valid, or served without the required intermediate chain.
- System time or container time is incorrect.
- A runtime trust store lacks the required CA, or an intercepting proxy presents a different chain.
Run a layered minimal diagnosis
Start with a request that has the fewest moving parts. Preserve the same account, API host, and target model while removing optional features.
Change one variable at a time and retain the raw status, headers, response body, and timing. This separates client serialization from gateway and upstream behavior.
- 01Establish the boundaryVerify host and container UTC time and NTP synchronization.
- 02Create a baselineConnect to the official hostname rather than an IP or internal alias.
- 03Compare one variableInspect issuer, SAN, validity, and the complete served chain without sending an API key.
- 04Record decisive evidenceCompare system, browser, Node.js, Python, and container CA stores.
HOST='<your-api-host>'
date -u
openssl s_client -connect "$HOST:443" -servername "$HOST" -showcerts </dev/null 2>/tmp/tls-debug.txt | openssl x509 -noout -subject -issuer -dates -ext subjectAltName
tail -n 5 /tmp/tls-debug.txt
Apply the fix at the confirmed root cause
Make the smallest change that addresses the proven layer. Avoid hiding deterministic configuration failures behind broad retries or disabled validation.
- 01Correct the failing layerServe a valid certificate for the requested hostname with the complete intermediate chain.
- 02Restore required behaviorInstall an approved organizational CA only in the intended managed trust store.
- 03Remove temporary workaroundsCorrect DNS or proxy routing while keeping hostname and certificate validation enabled.
Verify the repair, not just one successful call
Repeat the original path after the minimal check succeeds, then verify stable behavior under normal streaming, concurrency, and timeout conditions.
- The leaf and intermediate chain validates to an approved trust anchor.
- The request hostname appears in the certificate SAN.
- Browser, CLI, application runtime, and container all connect securely.
- No insecure flag or disabled TLS verification remains in config or CI.
Security boundaries and escalation evidence
Collect enough evidence to reproduce and escalate the failure without exposing credentials or weakening transport, permission, and validation controls.
- Never use insecure mode or globally disable certificate verification as a production fix.
- Do not send credentials during certificate inspection.
- Treat an unexpected issuer as a possible interception boundary.
- Escalate with hostname, issuer, SAN, validity, chain result, and runtime version.
Official sources and verification scope
This guide is grounded in protocol specifications and official client documentation. Error text, retry headers, and configuration fields may change by service or client version; verify the sources and redact logs and request samples before sharing.
Read the verification methodology