datasharingframework · jaboehri · Sep 18, 2025 · Sep 19, 2025 · Sep 19, 2025
diff --git a/docs/src/operations/troubleshooting/common-http-status-codes.md b/docs/src/operations/troubleshooting/common-http-status-codes.md
@@ -3,7 +3,19 @@ title: Common HTTP Status Codes
 icon: support
 ---
 
+# 401 Unauthorized
+This HTTP status code may be a result of an allow list mismatch. Either the requesting party is using a client certificate that was not updated after making changes to the allow list or the receiving party is using an outdated version of the allow list.
+
 # 403 Forbidden
-This HTTP status code may be encountered in many different way in the context of the DSF:
+This HTTP status code may be encountered in different ways in the context of the DSF:
 - Process plugin is not installed at FHIR server where the Task resource was posted
-- Client certificate of the FHIR server where the Task resource was posted is invalid
+- Client certificate of the FHIR server where the Task resource was posted is invalid e.g. because it is expired
+
+# 413 Content Too Large
+This HTTP status code is a result of trying to upload a resource that is too large for the server to handle. This might be due to a misconfiguration of the DSF FHIR server's reverse proxy not allowing this much data to be uploaded.
+
+# 500 Internal Server Error
+This HTTP status may be a result of a connection timeout if a forward proxy is used or when using ping pong 2.x in DSF 1.x with a download resource size of >400MB.
+
+# 502 Bad Gateway
+This HTTP status code is usually the response of a proxy because the server was unavailable or did not respond.
diff --git a/docs/src/operations/troubleshooting/connection-refused.md b/docs/src/operations/troubleshooting/connection-refused.md
@@ -1,4 +1,6 @@
 ---
 title: Connection Refused
 icon: cog
----
+---
+
+This error occurs when there is nothing listening on the port at the receiving end of a connection attempt or the firewall is blocking the connection. The former might indicate the reverse proxy for the DSF FHIR server being offline.
diff --git a/docs/src/operations/troubleshooting/connection-timeout.md b/docs/src/operations/troubleshooting/connection-timeout.md
@@ -10,4 +10,4 @@ There are many possible reasons for why this happens:
 - Firewalls might be blocking outgoing connections to the server
 - Arbitrary network issues
 
-If this is happens during the execution of a DSF process, it is recommended to try starting the process again to see if the issue persists. If the issue persists, it is recommended to ensure no firewall settings are blocking the outgoing connection attempt. If this is not the root of the issue, further troubleshooting has to take place that may have to include someone knowledgeable about the process plugin or someone from the team maintaining the server or a combination of both.
+If this is happens during the execution of a DSF process, it is recommended to try starting the process again to see if the issue persists. If the issue persists, further troubleshooting might have include system administrators or a member of the [DSF team](../../community/communication.md).
diff --git a/docs/src/operations/troubleshooting/read-timeout.md b/docs/src/operations/troubleshooting/read-timeout.md
@@ -7,6 +7,7 @@ A read timeout is a network error that usually happens when a resource is read f
 There are many possible reasons for why this happens:
 - The server unexpectedly went down during transmission
 - The server is under heavy load and unable to process the request in a timely manner
+- Ping pong 2.x may run in read timeouts if the download resource size too large. This can be mitigated by setting the `pong-timeout-duration` when starting the ping pong process, the environment variables `DEV_DSF_BPE_FHIR_CLIENT_REMOTE_TIMEOUT_READ` and `DEV_DSF_BPE_FHIR_CLIENT_LOCAL_TIMEOUT_READ` of the BPE and/or the `DEV_DSF_FHIR_CLIENT_TIMEOUT_READ` of the DSF FHIR server to higher values
 - Arbitrary network issues
 
-If this is happens during the execution of a DSF process, it is recommended to try starting the process again to see if the issue persists. If the issue persists, further troubleshooting has to take place that may have to include someone knowledgeable about the process plugin or someone from the team maintaining the server or a combination of both.
+If this is happens during the execution of a DSF process, it is recommended to try starting the process again to see if the issue persists. If the issue persists, further troubleshooting might have include system administrators or a member of the [DSF team](../../community/communication.md).
diff --git a/docs/src/operations/troubleshooting/unknown-host.md b/docs/src/operations/troubleshooting/unknown-host.md
@@ -3,4 +3,4 @@ title: Unknown Host
 icon: question
 ---
 
-This error occurs if a host name cannot be mapped to an IP address. Either because of a spelling mistake of the host name or because of DNS problems. If this happens in the context of a DSF process, it is recommended to review the configuration of the process plugin or contact the process plugin's maintainers in case of the former. DNS problems have a wide variety of sources and usually have to be resolved on the side of the sender.
+This error occurs if a host name cannot be mapped to an IP address. Either because of a spelling mistake of the host name or because of DNS problems. If this happens in the context of a DSF process, it is recommended to review the configuration of the process plugin or contact the process plugin's maintainers. DNS problems have a wide variety of sources like network misconfiguration or the DNS server being unavailable.