[DX-1962] docs: document timeout requirements for proxy_default_timeout > 120s (#1128)

Author: buger

api-management/troubleshooting-debugging.mdx

@@ -394,6 +394,24 @@ sidebarTitle: "Troubleshooting"
 
     You are able to see a more detailed output in your Gateway log `/var/log` or `/var/log/upstart`.
 
+18. Gateway `proxy_default_timeout` vs `http_server_options.write_timeout`
+
+    **Tyk to Upstream timeout**
+
+    `proxy_default_timeout` specifies the amount of time that Tyk will wait for the upstream service to complete its reply to Tyk
+
+    With gateways prior to release 5.0.7 `proxy_default_timeout` defaulted to zero which would result in the gateway waiting forever. This consumed resources and could lead to depletion of ephemeral sockets.
+
+    Since gateway 5.0.7 `proxy_default_timeout` defaults to 30 seconds.
+
+    When increasing `proxy_default_timeout` beyond 120 seconds it is necessary to consider the client to Tyk timeouts.
+
+    **Client to Tyk timeouts**
+
+    `http_server_options.write_timeout` specifies the number of seconds that Tyk will keep the client connection open for Tyk to write to it. If this is less than `proxy_default_timeout` then the connection to the client will be closed and the upstream reply will not be proxied back to the client if the upstream takes longer than `http_server_options.write_timeout` seconds. To avoid this please make sure that `http_server_options.write_timeout`is at least 1 second longer than `proxy_default_timeout`
+
+    `http_server_options.read_timeout` specifies that number of seconds that Tyk will allow the client to complete sending the request to it. This usually doesn't need to be changed since a lot of data can be sent in the default of 120 seconds, but it can be changed if needed.
+
 ## Gateway Error Response Status Codes
 
 Tyk Gateway responses include HTTP status codes that follow the [HTTP status code standard](https://datatracker.ietf.org/doc/html/rfc9110). They have three digits that describe the result of the request and the semantics of the response. 

snippets/gateway-config.mdx

@@ -159,6 +159,12 @@ Type: `int`<br />
 
 API Consumer -> Gateway network write timeout. Not setting this config, or setting this to 0, defaults to 120 seconds
 
+<Note>
+
+If you set `proxy_default_timeout` to a value greater than 120 seconds, you must also increase [http_server_options.write_timeout](#http-server-options-write-timeout) to a value greater than `proxy_default_timeout`. The `write_timeout` setting defaults to 120 seconds and controls how long Tyk waits to write the response back to the client. If not adjusted, the client connection will be closed before the upstream response is received.
+
+</Note>
+
 ### http_server_options.use_ssl
 ENV: <b>TYK_GW_HTTPSERVEROPTIONS_USESSL</b><br />
 Type: `bool`<br />
@@ -1009,6 +1015,12 @@ Type: `float64`<br />
 This can specify a default timeout in seconds for upstream API requests.
 Default: 30 seconds
 
+<Note>
+
+If you set `proxy_default_timeout` to a value greater than 120 seconds, you must also increase [http_server_options.write_timeout](#http-server-options-write-timeout) to a value greater than `proxy_default_timeout`. The `write_timeout` setting defaults to 120 seconds and controls how long Tyk waits to write the response back to the client. If not adjusted, the client connection will be closed before the upstream response is received.
+
+</Note>
+
 ### proxy_ssl_disable_renegotiation
 ENV: <b>TYK_GW_PROXYSSLDISABLERENEGOTIATION</b><br />
 Type: `bool`<br />