[BridgeLink 4.6.1] Timeout Handling – Best Practice Validation

[jewelbonnie]

[BridgeLink 4.6.1] Timeout Handling – Best Practice Validation

Hi team 👋,

We are working with BridgeLink 4.6.1 for file ingestion APIs (CSV, FHIR, etc.) and wanted to validate our current approach for handling long-running requests.

Context

In scenarios involving large or multiple file uploads, processing time can exceed the configured HTTP Listener timeout (around 30 seconds in our case).

Observed behavior

• BridgeLink returns HTTP 500 Internal Server Error after ~30–31 seconds
• Downstream processing continues and completes successfully
• UI reflects successful processing

Based on our understanding

• Timeouts are treated as transport-level exceptions
• These exceptions are returned as HTTP 500 by default
• This appears to be standard BridgeLink behavior

Goal

We want to ensure correct HTTP semantics without masking real errors.

Current approach

1. Error Classification (Postprocessor)

   • Inspect destinationResponse.getStatus()

   • Classify errors as:

     • Timeout → 504 Gateway Timeout
     • Connection issues → 502 Bad Gateway
     • Unexpected/internal errors → 500 (preserved)

2. Response Normalization

   • Update destination response in-place to prevent default 500 override
   • Return structured responses (FHIR OperationOutcome where applicable)

3. Processing Model

   • Currently using asynchronous processing (immediate=false)
   • Evaluating asynchronous handling with a 202 Accepted pattern for large payloads

Additional Observation

• When using synchronous mode (immediate=true) for large payloads:

  • Requests frequently hit the HTTP Listener timeout (~30s)
  • This results in HTTP 500 responses, even though backend processing completes successfully

Intent

• Avoid misleading 500 errors for timeout scenarios
• Preserve genuine server errors (no masking)
• Align responses with HTTP standards (504 / 502 / 500 / 202)
• Improve client experience

Questions

1. Does this approach align with recommended practices in BridgeLink?
2. Is using a Postprocessor-based normalization layer a common pattern?
3. Is there a native way to return 504 instead of 500 for timeouts?

Summary

We understand that the observed 500 responses are due to how BridgeLink handles timeout exceptions, and we have implemented a structured layer to align responses with standard HTTP semantics.

We would appreciate any feedback or suggestions to validate or improve this approach.

Thanks in advance!