diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md
index 2b20b5c..4ac6776 100644
--- a/docs/3.0-migration-guide.md
+++ b/docs/3.0-migration-guide.md
@@ -902,7 +902,7 @@
 accessing fields of `mbedtls_ssl_session` should describe their use case
 on the Mbed TLS mailing list.
 
-### Removal of some SSL error codes
+### Changes in the SSL error code space
 
 This affects users manually checking for the following error codes:
 
@@ -916,11 +916,11 @@
 Migration paths:
 - `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED` and `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH`
   should never be returned from Mbed TLS, and there is no need to check for it.
-  
+
   Users should simply remove manual checks for those codes, and let the Mbed TLS
   team know if — contrary to the team's understanding — there is in fact a situation
   where one of them was ever returned.
-  
+
 - `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` has been removed, and
   `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` is returned instead if the user's own certificate
   is too large to fit into the output buffers.
@@ -928,10 +928,29 @@
   Users should check for `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` instead, and potentially
   compare the size of their own certificate against the configured size of the output buffer to
   understand if the error is due to an overly large certificate.
-  
-- `MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN` and `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` have been replaced by `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE`
 
-- all codes of the form `MBEDTLS_ERR_SSL_BAD_HS_XXX` have been replaced by various alternatives.
+- `MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN` and `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` have been
+  replaced by `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE`.
+
+- All codes of the form `MBEDTLS_ERR_SSL_BAD_HS_XXX` have been replaced by various alternatives.
+
+  Users should check for the newly introduced generic error codes
+
+  * `MBEDTLS_ERR_SSL_DECODE_ERROR`
+  * `MBEDTLS_ERR_SSL_ILLEGAL_PARAMETER`,
+  * `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE`
+  * `MBEDTLS_ERR_SSL_BAD_PROTOCOL_VERSION`
+  * `MBEDTLS_ERR_SSL_BAD_CERTIFICATE`
+  * `MBEDTLS_ERR_SSL_UNRECOGNIZED_NAME`
+  * `MBEDTLS_ERR_SSL_UNSUPPORTED_EXTENSION`
+  * `MBEDTLS_ERR_SSL_NO_APPLICATION_PROTOCOL`
+
+  and the pre-existing generic error codes
+
+  * `MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE`
+  * `MBEDTLS_ERR_SSL_INTERNAL_ERROR`
+
+  instead.
 
 ### Modified semantics of `mbedtls_ssl_{get,set}_session()`