diff --git a/docs/reference/timeout-best-practices.md b/docs/reference/timeout-best-practices.md
new file mode 100644
index 000000000..8bb66f961
--- /dev/null
+++ b/docs/reference/timeout-best-practices.md
@@ -0,0 +1,13 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/timeout-best-practices.html
+---
+
+# Timeout best practices [timeout-best-practices]
+
+Starting in 9.0.0, this client is configured to not time out any HTTP request by default. {{es}} will always eventually respond to any request, even if it takes several minutes. Reissuing a request that it has not responded to yet can cause performance side effects. See the [official {{es}} recommendations for HTTP clients](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md#_http_client_configuration) for more information.
+
+Prior to 9.0, this client was configured by default to operate like many HTTP client libraries do, by using a relatively short (30 second) timeout on all requests sent to {{es}}, raising a `TimeoutError` when that time period elapsed without receiving a response.
+
+If you need to set timeouts on Elasticsearch requests, setting the `requestTimeout` value to a millisecond value will cause this client to operate as it did prior to 9.0.
+
diff --git a/docs/reference/toc.yml b/docs/reference/toc.yml
index 3896c1fde..9fbda6f58 100644
--- a/docs/reference/toc.yml
+++ b/docs/reference/toc.yml
@@ -31,4 +31,5 @@ toc:
       - file: update_examples.md
       - file: update_by_query_examples.md
       - file: reindex_examples.md
-  - file: client-helpers.md
\ No newline at end of file
+  - file: client-helpers.md
+  - file: timeout-best-practices.md
\ No newline at end of file