Troubleshoot Request Timeouts

Gateway timeouts can occur for various reasons. Use the following steps to identify the root cause of a timeout:

For detailed information on timeouts, see Timeouts and Limits.

Step 1: Identify Your Request

Every SCAPI response has a correlationID response header that you can use to identify and track request details for the request.

Determine the correlationID from your request with the timeout and gather log information:

In Business Manager, click App Launcher and then select Administration > Site Development > Development Setup.
In the Log Files section, select Log Center.
Select the Day of Year.
For LCQL, enter correlationID.
Make a note of the API-Family and API values for the next step.

Step 2: View Request Processing Time

Check for response times or processing times that are close to the timeout limits using Reports & Dashboards (CIP) data:

In Business Manager, click App Launcher and then select Merchant Tools > Select your site.
Go to Analytics > Reports and Dashboards.
Check the Average Response time for your API.

An average response time that is close to the timeout threshold might exceed the limit under high load. Timeout errors with a low average response time indicates occasional responses exceeding the limit. Although uncommon, network issues can also cause timeout issues.

Step 3: Gather Additional Request Details

To find the root cause of a gateway timeout, additional request details are needed:

request details
response details
customApi script, if the request is a custom API request
hooks executed during request processing including hook execution time for each hook

Try to reproduce the suspicious request with verbose logging enabled. For details, see: Additional request details. The Log Center provides request details via verbose log filter. Therefore, use the correlationID and the log level category scapi.verbose together.

Step 4: Check For Errors

In Log Center, using the query hits, filter for errors to find errors that occurred during request processing.

Investigating script errors

Check if those errors occur regularly and try to correlate them to long running requests.

Step 5: Identify Customized Code Executed During Request Processing

Hooks or custom scripts executed in Custom APIs might be the root cause of the timeout.

APIs that include hooks are always slower than APIs without hooks, because there is additional code to execute. Furthermore, Custom APIs and hooks contain a Circuit Breaker mechanism, which blocks API requests when a specific error threshold is exceeded.

Circuit-breaker

Check the Log Center query hits for the following exception types:

HookInvocationException
HookCircuitBreakerException
CustomApiInvocationException

Select the stacktrace to locate the Caused by section, which can contain information about the root cause of failures. Some possible causes include:

External requests that exceed a timeout
Complex computations
Script errors

A 504 response code returned by the API gateway might not be the same response code as displayed in the Log Center.

Note

Step 6: Improve Code and Customizations

Use the code profiler to monitor performance and locate performance bottlenecks.

Use additional log statements and metrics to gather more details.

General guidance:

Check requested expansions and only select required data. For details, see Server-Side Web-Tier Caching.
Only request required availability and personalized data.
Use caution with resource identifiers that allow multiple values such as category IDs or product IDs. These can result in a large amount of response data and increased response time.

Client side guidance:

Use compression.
Reuse authentication tokens.
Avoid external requests or use async processing (jobs).
Avoid complex processing and computations.