Improve SSL error message with helpful hints (#3713)

[rodrigobnogueira]

Improve SSL error message with helpful hints

Relates to #3713

Summary

When encountering [SSL: WRONG_VERSION_NUMBER] or [SSL: RECORD_LAYER_FAILURE] errors, the error message now includes a helpful hint about possible causes.

Changes

httpx/_transports/default.py:
Enhanced map_httpcore_exceptions to detect SSL handshake failures and append guidance.

Before:

ConnectError: [SSL: WRONG_VERSION_NUMBER] wrong version number (_ssl.c:1000)

After:

ConnectError: [SSL: WRONG_VERSION_NUMBER] wrong version number (_ssl.c:1000) (Hint: HTTPS to HTTP server, or stale connection pool)

The commited hint is a small message, but we could add a more detailed message, such as:

               " (Possible causes: 1) Connecting via HTTPS to an HTTP server, "
               "2) A pooled connection was closed by the server - "
               "try setting `limits=httpx.Limits(keepalive_expiry=2)` or retrying)"

Context

Users experiencing intermittent SSL errors in long-running containers (like the ECS scenario in #3713) face cryptic OpenSSL messages. The root cause is typically stale connections being reused after the server silently closed them. This hint points users in the right direction.

Tests

Added test_ssl_error_message_enhancement in tests/test_exceptions.py.

Checklist

• I understand that this PR may be closed in case there was no previous discussion. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.

[Mahnoor-Zaffar]

Reviewed: httpx/_transports/default.py, tests/test_exceptions.py. CI: all checks passing.

• The enhancement to the error message in map_httpcore_exceptions is clear and provides valuable guidance for users encountering SSL errors. The hints about possible causes are a great addition.
• The test test_ssl_error_message_enhancement effectively covers the new behavior by checking both error messages and ensuring the hints are included. This should help catch regressions related to SSL error handling.

Overall, the changes are well-implemented and should improve user experience significantly. Nice work!

[rodrigobnogueira]

Project migrated.