API Reliability
cURL TLS Debugging Guide
Use cURL verbose output to separate DNS, TCP, certificate chain, hostname, protocol and proxy failures without disabling verification. This reference is written for developers who need practical validation behavior, reviewable rules and safe examples rather than copied snippets with no explanation.
Recommended workflow
| Step | Why it matters |
|---|---|
| Confirm the hostname | Check DNS results and ensure the requested hostname matches the certificate identity. |
| Read the TLS phase | Verbose output shows protocol negotiation, certificate verification and proxy behavior. |
| Inspect the chain | Use an SNI-aware certificate check to find missing intermediates or an unexpected issuer. |
| Fix trust deliberately | Update the server chain or trusted CA bundle instead of reaching for insecure mode. |
Starter snippet
curl --verbose --connect-timeout 5 https://api.example.test/health
openssl s_client -connect api.example.test:443 -servername api.example.testReview checks
- Keep system time accurate.
- Test through the same proxy path as the failing client.
- Redact authorization headers from verbose output.
- Verify IPv4 and IPv6 paths when results differ.
Common mistakes
- Using curl -k as the final fix.
- Testing an IP address while expecting hostname verification to pass.
- Blaming TLS when a corporate proxy replaced the certificate.
Validation should help users correct input while protecting systems from bad data. Keep syntax checks, product policy, security review and deliverability checks separate.
Related Formalint references
Continue with Tls Certificate Debugging Guide, Ssl Renewal Debugging Guide, Curl Api Debugging Cheatsheet.