Troubleshoot Request Timeouts

SCAPI requests have a request timeout limit. If the request processing exceeds the limit, a 504 gateway timeout response is sent to the client.

The default timeout limits are:

  • Shopper-APIs: 10 seconds
  • Admin-APIs: 60 seconds
  • Custom-APIs: 10 seconds

Some API families, such as SLAS and Omnichannel Inventory (OCI), do not have gateway timeouts.

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

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:

  1. In Business Manager, navigate to Administration > Site Development > Development Setup.
  2. In the Log Files section, select Log Center.
  3. Select the Day of Year.
  4. For LCQL, enter correlationID.
  5. Make a note of the API-Family and API values for the next step.

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

  1. In Business Manager, navigate to Merchant Tools > Select your site.
  2. Go to Analytics > Reports and Dashboards.
  3. 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.

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.

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.

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.

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](b2c-site-performance.html.
  • Reuse authentication tokens.
  • Avoid external requests or use async processing (jobs).
  • Avoid complex processing and computations.