docs: document about global dispatcher and errors (#3987) (#4014)

* docs about global dispatcher and errors (#3987)

Signed-off-by: Konrad Baumgart <[email protected]>

* Update docs/docs/api/Errors.md

Co-authored-by: Carlos Fuentes <[email protected]>

---------

Signed-off-by: Konrad Baumgart <[email protected]>
Co-authored-by: Konrad Baumgart <[email protected]>
Co-authored-by: Matteo Collina <[email protected]>
Co-authored-by: Carlos Fuentes <[email protected]>

Author: 4 people

README.md

@@ -337,7 +337,8 @@ See [Dispatcher.upgrade](./docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-
 
 * dispatcher `Dispatcher`
 
-Sets the global dispatcher used by Common API Methods.
+Sets the global dispatcher used by Common API Methods. Global dispatcher is shared among compatible undici modules,
+including undici that is bundled internally with node.js.
 
 ### `undici.getGlobalDispatcher()`
 

docs/docs/api/Errors.md

@@ -28,6 +28,7 @@ import { errors } from 'undici'
 | `ResponseExceededMaxSizeError`       | `UND_ERR_RES_EXCEEDED_MAX_SIZE`       | response body exceed the max size allowed                                 |
 | `SecureProxyConnectionError`         | `UND_ERR_PRX_TLS`                     | tls connection to a proxy failed                                          |
 
+Be aware of the possible difference between the global dispatcher version and the actual undici version you might be using. We recommend to avoid the check `instanceof errors.UndiciError` and seek for the `error.code === '<error_code>'` instead to avoid inconsistencies.
 ### `SocketError`
 
 The `SocketError` has a `.socket` property which holds socket metadata: