Read the error as a clue about the request path
A 502 or 504 error tells you that a gateway or proxy could not complete its exchange with an upstream service in the expected way. A 502 indicates an invalid upstream response; a 504 indicates that the response did not arrive in time. Neither status identifies a particular Magento module, proves that the database is down or tells you whether an attempted payment completed.
Start by recording the exact status, affected URL, customer action and time with its time zone. Keep any non-sensitive request identifier from the error page. Note whether the problem affects every route or only a dynamic action. That evidence helps the hosting provider and application team follow the same request instead of investigating separate incidents.
Decide what is failing for customers
Check a small number of representative journeys without creating repeated orders or charges. Can visitors open the homepage, browse a product and view an existing basket? Does the failure happen when selecting delivery, logging in or placing an order? A cached landing page can remain available while the backend is unhealthy, so a successful homepage request is not enough to declare recovery.
If trading is blocked, use the emergency support route. Explain what customers cannot do and whether payment or order outcomes are uncertain. For a broader outage with a 503 response, the 503 recovery guide provides related checks. The visible code may differ between infrastructure layers for the same underlying incident.
- 01RecordTime, route, response and business impact
- 02LocateWhich intermediary produced the error
- 03CorrelateUpstream logs, capacity and request state
- 04ReconcileRecover the journey and check order outcomes
Identify which component returned the error
Map the normal request path: browser, CDN or proxy, web server, PHP/application and the services the application depends on. Your store may have fewer or more layers. Use the response and correlated logs to determine which layer generated the error and which upstream it was waiting for. Do not infer the topology from a familiar-looking error page alone.
For Adobe Commerce on Cloud, Adobe documents platform-specific Fastly and application log checks. A self-hosted Magento installation will have different locations and responsibilities. A provider may be able to correlate the failed request with an upstream reset, a process restart or a timeout. Ask for that evidence before changing several timeout values at once.
Follow the request into the bottleneck
A request may wait for a PHP worker before application code runs. Once running, it may wait for database work, a lock, an external API or another service. These are different stages. Compare request timestamps with worker availability, application traces and dependency timings where access permits. A server-wide CPU average may miss a specific blocked operation.
If workers are saturated, inspect why they remain busy before increasing concurrency. If a database operation is waiting, follow the transaction and its competing workload. If a shipping or payment dependency is slow, review how the integration handles timeouts and uncertain outcomes. Our guides to PHP-FPM worker saturation and database contention cover those branches in more detail.
| Observation | Meaning or next question |
|---|---|
| 502 response | A gateway reports an invalid response from an upstream server. |
| 504 response | A gateway did not receive an upstream response in time. |
| Checkout affected | Did the operation complete despite the failed browser response? |
| All routes affected | Look for a shared dependency or capacity problem. |
| One route affected | Follow the application work and external calls on that route. |
Do not make a timeout change the whole diagnosis
Increasing a timeout can sometimes be appropriate for a known operation, but it does not remove the work that caused the delay. It can also leave workers occupied for longer or move the failure to another layer. The decision should connect an expected operation duration, the relevant upstream and the capacity consequences.
A customer-facing checkout action and an authorised administrative export may deserve different handling. Before changing limits, ask whether the operation belongs in a background process, whether the caller can observe its progress and how it is made safe to retry. A successful response after a much longer wait is not necessarily an acceptable customer experience.
Treat payment and order outcomes as uncertain until reconciled
If the error appeared after “Place order”, the browser's failure is not proof that no business transaction occurred. Check the actual Magento order and the provider's payment record through authorised tools before repeating the action. A new attempt can create duplicate activity even when the first response never reached the customer.
Use the payment-taken-but-no-order guide for that reconciliation path. If asynchronous payment notifications are failing, review payment webhook failures. Do not mark an order paid, capture another payment or issue a refund solely to make the visible states match; establish the underlying outcome first.
Contain the incident with a reversible decision
Preserve the timeline and relevant logs before actions that could remove useful evidence. If a recent release or scheduled job clearly aligns with the incident, the authorised owner can assess whether pausing that workload or reverting a compatible change is a safe containment. Record the decision, the expected effect and how it will be checked.
Avoid unplanned cache purges, database clearing or repeated service restarts. Those actions may temporarily change symptoms while erasing the conditions needed to diagnose them. A restart can be a legitimate recovery action when justified, but it should be connected to evidence and followed by verification of orders, queues and customer journeys.
Verify the full recovery path
Repeat the original failed action safely and check its outcome, then verify nearby journeys. Confirm that the error rate remains stable and that queued work is not continuing to accumulate. Where the symptom depended on load, a quiet successful request does not prove that the original capacity issue is gone.
Record the immediate containment separately from the durable correction. If the store was restored by reducing a workload, the cause of the excessive work may still need planned investigation. A Performance Investigation can be appropriate once trading is stable and the evidence points to a persistent application or infrastructure constraint.
Prepare a concise escalation brief
Send the domain, first observed time, affected actions, exact status and recent changes. State whether all visitors are affected or whether the issue is intermittent. Include request identifiers or redacted examples when available, but keep credentials and customer data out of general email. Identify the hosting and application contacts who can inspect their respective layers.
The brief should separate confirmed facts from hypotheses. “The checkout request received a 504 at 14:20 UK time” is a fact if observed. “The database is broken” is a hypothesis until supported. Clear language allows the response team to investigate quickly without treating an early guess as an instruction to make an irreversible change.
Common questions
Is a 504 always a hosting fault?
No. The gateway timed out waiting for an upstream response, but application work or a downstream dependency may explain the delay. Correlated evidence is needed to identify responsibility.
Can customers retry after a gateway error?
For an ordinary read-only page, a later reload may be reasonable. After an order or payment action, reconcile the outcome before asking for another attempt. The error does not prove that the original operation failed completely.
Will clearing Magento cache fix a 502?
There is no universal relationship. A purge may increase backend work and worsen an overloaded system. Only use it when the investigation provides a specific reason and the impact is understood.
Technical references
Use the documentation that matches your installed version, payment provider and deployment.