Inconsistent certificate pinning errors during proxy routing in Reach

Answering the Core Question

When Reach’s native networking bridge encounters a certificate‑pinning mismatch while traffic is routed through a corporate proxy, it reports the failure through a small, well‑defined exception hierarchy. The most common top‑level type is ReachPinningException, which is a subclass of the generic ReachNetworkException. The ReachPinningException usually wraps a standard Java/Android SSLHandshakeException, whose root cause is an SSLPeerUnverifiedException. This chain signals that the TLS handshake succeeded from the OS perspective but the certificate presented did not match the pin set in the Reach configuration.

In contrast, DNS‑level problems surface earlier in the connection pipeline. A proxy that mis‑resolves a host or a stale OS DNS cache will cause UnknownHostException or ConnectException before any TLS negotiation takes place. Reach will surface these as plain ReachNetworkException instances without the SSLHandshakeException wrapper.

How to Distinguish the Two Scenarios

1. Inspect the exception class hierarchy. A ReachPinningException with an SSLHandshakeException cause indicates a TLS‑level rejection, not a DNS issue.
2. Check the cause chain. If the root cause is SSLPeerUnverifiedException, the OS TLS stack rejected the certificate. If the root cause is UnknownHostException or ConnectException, it’s a DNS cache conflict.
3. Verify proxy behavior. If the corporate proxy performs TLS interception (MITM), the OS will reject the proxy’s certificate unless its CA is trusted. Installing the proxy’s CA into the OS trust store should eliminate the SSLPeerUnverifiedException. If the proxy merely forwards traffic, the failure will remain in the ReachPinningException chain.
4. Test without the proxy. Running the same request with the proxy disabled should shift the error from SSLPeerUnverifiedException to a DNS‑related exception if the root cause was the proxy’s CA.

Documentation and Limitations

There is no public, version‑specific error‑code table that cleanly separates framework‑level DNS cache conflicts from OS‑level TLS rejections in Reach. The distinction must be inferred from the exception type and its cause chain, as described above. The Reach SDK’s internal exception classes are not exposed in the public API, so developers rely on log inspection or custom exception‑wrapping logic to surface the difference to end‑users.

What’s Missing?

To fine‑tune the recommendation, it would help to know whether the corporate proxy performs TLS interception (MITM) or simply forwards traffic. This detail determines whether the OS TLS stack or Reach’s pinning logic is the primary failure point.