502 and 503 Errors Explained: A Step-by-Step Guide to Finding the Hosting Failure
A 502 or 503 error usually means a request reached part of your web stack but could not be completed. This guide gives you a repeatable way to identify whether the failure is in the reverse proxy, web server, PHP-FPM, application, database, DNS, or hosting resources—and shows what to check before restarting or rolling back anything.
Overview
Both errors are server-side HTTP responses, but they point to different failure patterns. A 502 Bad Gateway means a gateway or reverse proxy received an invalid response, no response, or an unexpected connection failure from an upstream service. Common upstreams include PHP-FPM, an application server, a container, or another internal service.
A 503 Service Unavailable means the server is currently unable to handle the request. It may be overloaded, undergoing maintenance, unable to reach a required application process, or deliberately returning a temporary-unavailable response. A hosting provider, CDN, load balancer, web server, or application can generate the visible 503 page, so the status code alone does not identify the failing component.
Start by preserving evidence. Record the time, URL, HTTP method, client or monitoring location, response headers, deployment history, and whether the problem affects every page or only one route. Avoid repeatedly restarting services before checking logs; a restart can remove useful process-state evidence and can hide a capacity or configuration problem that will return.
If the issue is intermittent, compare your observations with an uptime monitoring record. The website uptime monitoring guide explains which response-time, status-code, and location details are useful during an incident.
What to track
1. Confirm the response and its source
Test the affected URL from more than one network where possible. Capture headers with a command such as:
curl -I https://example.com/affected-path
curl -sS -D - -o /dev/null https://example.com/affected-pathLook for headers identifying a CDN, proxy, web server, cache layer, or application. A response generated by a proxy may contain different headers from one generated by the origin. Test the origin directly only if your architecture and access controls allow it; do not expose an administrative origin just to make troubleshooting easier.
2. Check the request path in order
Trace the request from the edge inward:
- DNS: Confirm that the hostname resolves to the intended proxy or server. Check A, AAAA, CNAME, and relevant NS records, especially after a migration or DNS change. The DNS records guide provides a useful reference.
- TLS and edge proxy: Check whether the proxy can connect to the origin and whether the origin certificate, hostname, port, and protocol match the configured settings.
- Web server: Review Nginx, Apache, or another front-end server’s error log and access log around the exact failure time.
- Application gateway: Confirm that the configured upstream socket, port, container, or service name exists and is reachable.
- Runtime: Check PHP-FPM, Node.js, Python, Java, or another application process for crashes, timeouts, rejected connections, or exhausted workers.
- Database and dependencies: Test database connectivity, connection counts, queue services, APIs, and storage mounts used by the failing route.
3. Inspect logs and process health
Log locations vary by operating system, hosting control panel, container image, and deployment method. Typical locations include Nginx logs under /var/log/nginx/, Apache logs under /var/log/apache2/ or /var/log/httpd/, and PHP-FPM logs under a distribution- or pool-specific path. Managed WordPress hosting and shared hosting may expose equivalent data through a control panel rather than shell access.
Search for messages such as upstream timed out, connection refused, no live upstreams, connect() failed, server reached pm.max_children, worker termination, out-of-memory events, or syntax errors after a PHP or application configuration change. On a systemd-based server, service status and recent journal entries can help:
systemctl status php-fpm
journalctl -u php-fpm --since "15 minutes ago"
ss -ltnpThe service name may include a PHP version, such as php8.2-fpm, and the correct command depends on the installed stack. Do not assume that a PHP-FPM restart command or socket path remains unchanged after a PHP upgrade.
4. Check resources before changing limits
Review CPU, memory, disk space, inode usage, process counts, connection counts, and load during the incident. A full disk can prevent logs, sessions, cache files, or uploads from being written. Memory pressure can kill PHP-FPM or application workers, while a low worker limit can cause queues and timeouts without making CPU usage look high.
In shared hosting, check account-level CPU, memory, entry-process, and I/O limits in the hosting panel. In VPS or cloud hosting, inspect the virtual machine, container, load balancer, and database separately. Increasing a timeout or worker limit without confirming available memory can turn a recoverable overload into a larger failure.
5. Compare changes and isolate the failing layer
List deployments, plugin or theme updates, PHP version changes, DNS edits, SSL changes, firewall changes, infrastructure scaling events, and scheduled jobs immediately before the first error. If only one route fails, compare its application code, database query, authentication path, and external dependencies with a known-good route. If every route fails, prioritize the proxy, web server, runtime, DNS, and resource checks.
| Observed symptom | Likely area | First useful check |
|---|---|---|
| 502 immediately after a PHP or server change | PHP-FPM socket, port, or configuration | Compare the proxy upstream setting with the active PHP-FPM listener and review service logs. |
| 502 after a period of slow requests | Application, database, or upstream timeout | Match proxy and runtime timestamps; inspect slow requests, database connections, and worker saturation. |
| 503 on all pages | Maintenance mode, stopped service, overload, or provider layer | Check maintenance flags, service status, resource limits, and provider status information. |
| 503 on one feature or API route | Application dependency or route-specific capacity | Review application logs, dependency responses, queues, and recent code changes for that route. |
| Errors from some locations only | DNS, CDN, load balancing, or regional origin reachability | Compare DNS answers, response headers, monitoring locations, and edge-to-origin connectivity. |
Cadence and checkpoints
Use the same diagnostic checklist during every incident, then review the recorded variables monthly or quarterly. Consistency makes recurring failures easier to distinguish from unrelated outages.
- During an incident: Record timestamps, affected URLs, status codes, headers, logs, active processes, resource usage, recent changes, and every mitigation.
- After recovery: Confirm that the response is successful from multiple locations, check error rates for at least the relevant traffic period, and verify that background jobs, queues, database writes, and scheduled backups are operating.
- Monthly: Review the count and duration of 502 and 503 responses, the most affected routes, resource peaks, PHP-FPM worker usage, disk growth, and deployment-related incidents.
- Quarterly: Test a backup restore, review alert thresholds, verify rollback instructions, check DNS and certificate ownership, and confirm that the documented log paths and service names still match the current hosting stack.
Keep a short incident record even when the fix is a restart. Note what restarted, why it helped, and whether the underlying cause was confirmed. This prevents a temporary recovery from being mistaken for a permanent fix.
How to interpret changes
A rising 502 rate after a deployment points first to the changed application, runtime configuration, upstream endpoint, or dependency. A rising 503 rate during traffic peaks points toward capacity, queueing, worker exhaustion, or an intentional protection mechanism. Neither interpretation is conclusive until logs and timing support it.
If the proxy reports connection refused, the upstream process may be stopped, listening on another port or socket, blocked by permissions, or repeatedly crashing. If it reports a timeout, investigate slow application code, database locks, external APIs, network paths, and mismatched timeout settings. If PHP-FPM reports that its worker pool is full, determine whether requests are genuinely slow, traffic has changed, or the pool is undersized for available memory.
Separate failure from presentation. A CDN or reverse proxy may cache an error page, an application may convert an internal exception into a 503, and a health check may mark an origin unavailable while normal requests still work. Compare access logs at each layer and use a unique request identifier when your stack supports one.
Choose a rollback when a recent, reversible change aligns closely with the first failure and the service is materially impaired. Before rolling back, preserve logs and confirm that the prior version is available and compatible with current database migrations. If rollback is unsafe or the cause is resource exhaustion, stabilize first by reducing expensive traffic, disabling a failing feature, or adding capacity under controlled conditions. Then address the root cause.
When to revisit
Revisit this workflow after any hosting migration, DNS change, reverse-proxy change, PHP or runtime upgrade, web server configuration edit, database move, SSL change, CDN change, or major application deployment. These events can alter log locations, service names, PHP-FPM socket paths, timeout defaults, health checks, and resource limits.
Update your runbook monthly or quarterly when your infrastructure changes, not only when an outage occurs. Add the exact commands, control-panel locations, alert links, rollback steps, and escalation contacts that apply to your environment. Review whether backups are available before a rollback or migration; the website backup strategy guide covers testing and restoring offsite copies.
For a practical next step, create a one-page incident checklist containing: the failing URL, first-seen time, response headers, DNS result, proxy log line, application log line, process status, resource snapshot, recent changes, mitigation, and confirmed root cause. Run it once during a quiet period so you know where the evidence lives. When the next 502 or 503 appears, you can investigate the hosting failure systematically instead of guessing.
