Code change:
2.3.23. <del> Name: tls_expired_peer_certificate Description: The intermediary received an expired peer certificate during TLS handshake with the next hop. Extra Parameters: None. Recommended HTTP status code: 502 2.3.24. Name: tls_unexpected_peer_certificate Description: The intermediary received an unexpected peer certificate (e.g., SPKI doesn't match) during the TLS handshake with the next hop. Extra Parameters: identity: a sf-string containing a comma-separated list of Subject Alternative Names from the certificate received from the next hop. sha256: a sf-string containing the hex-encoded SHA-256 of the certificate received from the next hop. spki: a sf-string containing the base64-encoded SHA-256 of the Subject Public Key Info (SPKI) from the certificate received from the next hop. Recommended HTTP status code: 502 2.3.25. Name: tls_missing_proxy_certificate Description: The next hop requested a client certificate from the intermediary during TLS handshake, but it wasn't configured with one. </del> <ins> Name: tls_alert_received </ins> <del> Extra Parameters: None. Recommended HTTP status code: 500 2.3.26. Name: tls_rejected_proxy_certificate Description: The next hop rejected the client certificate provided by the intermediary during TLS handshake. Extra Parameters: None. Recommended HTTP status code: 500 2.3.27. Name: tls_error Description: The intermediary encountered a TLS error when communicating with the next hop. </del> <ins> Description: The intermediary received a TLS alert from the next hop. </ins> Extra Parameters:

Related discussion:
text: However, having only a generic "catch-all" error with the real reason "hidden" in a free-form text in , that's going to vary from implementation to implementation, is going to make this less useful for any kind of automated processing and/or analysis. Ideally, I think, we should have specific enums that cover 95%+ of reasons happening in production, and only use the generic "catch-all" error for things not covered by them... So, playing the devil's advocate, perhaps we should add a few more? (Note that there is already raised on mismatched identity, SHA256, SPKI or other missed expectations.) Also, if you can get your hands on errors happening in production, that could help us make more informed decision here.
I agree we shouldn't do a 1:1 mapping (especially with a library), but the hierarchy needs to be clear, and mapped to terminology used in the standards. I.e., there should be a generic catch-all 'cert error' code, and then more specific ones for the major classes of problems.
TLS itself also contains a pile of certificate-verification-related alerts. Although I think the set is mostly just carried over from SSL. URL NAME may also have some thoughts on certificate verification error-reporting.
Despite what libraries may provide, for their developers, is fairly clear: the only defined result is a I think coupling any protocol-level expectation about diagnostics for errors is fundamentally misaligned. It should not matter, for example, whether a particular library checks the validity period of the certificate before the signature. We know, empirically, that different libraries do very different things there: macOS vs Mozilla NSS vs Microsoft CryptoAPI each verify something like validity at different points within their verification algorithms. We know it's deeply flawed to view there being "the" certificate chain for a server, because by definition, the chain is defined by the client's policy and set of trust anchors. As a consequence, we know that clients SHOULD implement certificate path building, to explore possible certificate chains, and we know that TLS 1.3 was explicitly updated to reflect those decades of running code and the emergent rough consensus that the message, beyond the first , is an attempt to aid/influence that. is a huge collection of different ways verifiers can process and examine errors, during forward path building and reverse verification, and notes that the trade-offs are heavily dependent upon client and use cases.