503 first byte timeout errors for slow API requests
API requests to Adobe Experience Manager (AEM) as a Cloud Service that take longer to process than the CDN’s timeout window allow can return a 503 Service Unavailable error with a first byte timeout reason. To resolve this, move long-running operations off the request/response cycle and run them asynchronously, then have the client poll for the result instead of waiting on a single response.
Description description
Environment
- Adobe Experience Manager as a Cloud Service
- API requests routed through the AEM-managed CDN to the AEM publish tier
Issue/Symptoms
When you make an API request to an AEM endpoint that requires significant processing time, you might receive a 503 Service Unavailable error with an first byte timeout reason. This error occurs when the CDN layer closes the connection because it does not receive a response from AEM within the configured timeout window. The backend processing can complete successfully, but the client does not receive a response because of the timeout. This issue can affect GET and POST requests that involve long-running synchronous operations.
Resolution resolution
Use the following steps to resolve the issue.
- Identify the API endpoints or servlets that perform long-running synchronous processing, such as data exports or batch operations.
- Refactor these operations to run asynchronously in the background so they are not tied to the client connection. Use AEM’s workflow engine, job queues, or scheduled tasks for background processing.
- Update your client logic to start the long-running operation, then poll for status or completion instead of waiting for a single synchronous response.
- When the background job completes, provide the results to the client through polling, webhooks, or by making the result available for download.
- Confirm the CDN timeout window for your environment before you consider changing configuration. First byte timeouts on the standard AEM-managed CDN path are a platform-level protection and are not typically adjustable per API. If you route traffic through a custom origin using
originSelectors, a per-origintimeoutvalue is configurable, but it applies only to traffic sent to that custom origin, not to standard AEM publish requests. - After you make these changes, test your API endpoints to confirm that requests no longer result in 503 first byte timeout errors and that clients receive results as expected.