How to Fix HTTP 503 Service Unavailable Error

In this tutorial, you'll learn about How to Fix HTTP 503 Service Unavailable Error. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

The Problem

Your API client receives:

HTTP/1.1 503 Service Unavailable

The server is temporarily unable to handle the request due to a temporary overload or scheduled maintenance.

Quick Fix

1. Check server resource usage

High CPU, memory, or disk usage can cause 503:

# Check CPU and memory
top -bn1 | head -20

# Check disk space
df -h

# Check memory usage
free -h

If any resource is near 100%, the server is rejecting new connections.

2. Restart the application

A temporary restart may clear the issue:

sudo systemctl restart myapp

3. Check for maintenance mode

The application may be in maintenance mode intentionally:

# Check if a maintenance flag file exists
ls -la /var/www/app/maintenance.flag

# Or check the application config
grep MAINTENANCE /etc/myapp/config.env

Disable maintenance mode:

rm /var/www/app/maintenance.flag
# or restart without the maintenance flag

4. Check database Connection Pool

A exhausted database Connection Pool causes 503:

// Check PostgreSQL max connections
SELECT count(*) FROM pg_stat_activity WHERE state = 'active';

// Check MySQL connections
SHOW STATUS LIKE 'Threads_connected';

Increase the pool size or reduce application connections.

5. Scale resources

If the server is overloaded, scale up:

# Check if auto-scaling is working
kubectl get pods
kubectl get hpa

# Manual scale
kubectl scale deployment myapp --replicas=5

6. Check the web server connection limit

# Nginx — increase worker connections
events {
    worker_connections 2048;  # increase from default 768
}

# Check current connections
sudo ss -s

Prevention

• Set up auto-scaling for production workloads.
• Monitor CPU, memory, disk, and connection usage with alerts.
• Use a CDN to absorb traffic spikes.
• Implement graceful degradation for dependency failures.
• Plan maintenance Windows and communicate them to users.

Common Mistakes with 503 unavailable

1. Mixing let bindings with <- bindings in do notation, producing type errors
2. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
3. Non-exhaustive pattern matches that compile with warnings then crash at runtime

These mistakes appear frequently in real-world API code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ