Diagnosing HTTP Request Timeouts and 5xx Errors in Node‑RED Flows

Problem Statement

In many Node‑RED deployments the node‑red‑contrib‑http‑request node is used to call external APIs. A common symptom is the node repeatedly timing out or returning HTTP 5xx responses. This can halt downstream processing, waste resources, and obscure the real cause of failure. The goal of this guide is to provide a concise diagnostic workflow that lets you pinpoint the root cause quickly and apply the appropriate fix.

Cause–Diagnostic Table

Observed Symptom	Likely Cause	Primary Check
Node status shows timeout or 5xx	Network unreachable or endpoint overloaded	Ping / curl connectivity test
Node status shows timeout only after a long period	Request timeout too short for slow API	Inspect node timeout setting
Node status shows 5xx consistently	Server error or malformed request triggering 5xx	Validate request method, headers, body
Node status shows 401/403 but logged as 5xx	Missing or expired auth token	Check credential storage and token refresh logic
Logs contain TLS handshake errors	Outdated CA certificates or TLS mismatch	Verify CA bundle on Node‑RED host

Ordered Checklist

1. Verify Host Connectivity
   

   Run from the Node‑RED host:

   ping -c 4 api.example.com
   curl -I https://api.example.com/v1/resource

   Replace api.example.com with the target. A successful 200 response and no network errors confirm that the host can reach the API.

2. Confirm HTTP Method & Payload
   

   Open the flow editor, double‑click the HTTP request node, and verify that the Method field matches the API spec (GET, POST, etc.). For POST/PUT, ensure the Payload tab contains the correct JSON or form data and that the Content-Type header is set accordingly.

3. Check Timeout Setting
   

   The default timeout is 120 s. If the API is known to take longer, increase the timeout in the node’s Timeout field or enable the Retry option. Avoid values over 10 min to prevent worker starvation.

4. Inspect Node‑RED Logs
   

   Run Node‑RED in the terminal (node-red) or use the built‑in debug tab. Look for entries like:

   node-red-contrib-http-request: Error 504 (Gateway Timeout) for https://api.example.com/v1/resource

5. Validate Authentication
   

   Ensure that the Authorization header contains a valid token. In Node‑RED, store tokens in the Credentials tab of the node rather than hard‑coding them. If the API uses OAuth2, confirm that the refresh flow is working.

6. Verify TLS Configuration
   

   If the API uses HTTPS, run:

   openssl s_client -connect api.example.com:443 -CAfile /etc/ssl/certs/ca-certificates.crt

   Check for handshake errors. Update the CA bundle on the Node‑RED host if needed.

7. Test with a Minimal Flow
   

   Create a new flow containing only an inject node (payload: {}), the HTTP request node, and a debug node. This isolates the node from surrounding logic and confirms whether the issue is node‑specific or flow‑wide.

8. Check Network Policies
   

   If the host is behind a corporate proxy, ensure that http_proxy and https_proxy environment variables are set for Node‑RED, or configure the node to use the proxy via its Proxy field.

Quick Fixes Tied to Findings

• Connectivity Failure → Add a static route or adjust firewall rules to allow outbound traffic to the API domain.
• Timeout Too Short → Increase the Timeout value or enable Retry with exponential back‑off.
• Malformed Request → Update the Method, Headers, and Payload to match the API spec; use a http request node’s Response tab to verify the returned body.
• Auth Token Issues → Refresh the token, store it in credentials, and add a function node to inject the header dynamically.
• TLS Handshake Errors → Install the missing CA certificates or add rejectUnauthorized: false (not recommended for production) in the node’s advanced settings.
• Proxy Blockage → Configure Node‑RED’s http_proxy env var or set the Proxy field in the node.

Escalation Criteria

If after applying the above steps the node still times out or returns 5xx errors, consider:

• Contacting the API provider’s support team with the exact request details and error logs.
• Deploying a test instance of Node‑RED on a different host or network to rule out host‑specific issues.
• Using a network monitoring tool (e.g., Wireshark) to capture the TLS handshake and HTTP traffic for deeper analysis.
• Reviewing the API’s rate‑limiting or maintenance status; a 5xx could indicate a temporary outage.

Limitations & Practical Verification

Node‑RED’s node-red-contrib-http-request node does not expose all underlying HTTP client options. For complex scenarios, consider using a function node with node-fetch or axios for finer control. Always test changes in a staging environment before applying them to production.

To verify that a fix worked, enable the debug node on the HTTP request’s output and confirm that the statusCode field matches the expected value (e.g., 200) and that the payload contains the expected data.