Skip to main content

PatchMon Rate Limiting Guide

PatchMon Rate Limiting Guide

Overview

PatchMon implements rate limiting to protect your instance from abuse, brute force attacks, and excessive load. This guide explains how rate limiting works, how to identify rate limit issues, and how to adjust limits for your deployment.

Understanding HTTP 429 Errors

When rate limits are exceeded, the API returns an HTTP 429 status code with the message "Too Many Requests". This indicates that the client has sent too many requests in a given time window and should retry after the specified period.

Default Rate Limits

PatchMon uses three different rate limiters for different types of endpoints:

General API Rate Limit

Applies to most API endpoints.

Setting Default Value Description
RATE_LIMIT_WINDOW_MS 900000 Time window in milliseconds (15 minutes)
RATE_LIMIT_MAX 5000 Maximum requests allowed per window

Default: 5000 requests per 15 minutes

Authentication Rate Limit

Applies to authentication endpoints (/api/*/auth).

Setting Default Value Description
AUTH_RATE_LIMIT_WINDOW_MS 600000 Time window in milliseconds (10 minutes)
AUTH_RATE_LIMIT_MAX 500 Maximum auth requests allowed per window

Default: 500 requests per 10 minutes

Agent API Rate Limit

Applies to agent/host management endpoints (/api/*/hosts).

Setting Default Value Description
AGENT_RATE_LIMIT_WINDOW_MS 60000 Time window in milliseconds (1 minute)
AGENT_RATE_LIMIT_MAX 1000 Maximum agent requests allowed per window

Default: 1000 requests per minute

Identifying Rate Limit Issues

Symptoms

  • HTTP 429 errors in application logs
  • Agents failing to report or update
  • Users unable to authenticate or access the dashboard
  • API requests timing out or failing

Checking Rate Limit Status

The backend includes standard rate limit headers in API responses that help you monitor your usage:

Header Description
RateLimit-Limit Maximum requests allowed in the current window
RateLimit-Remaining Number of requests remaining in current window
RateLimit-Reset Unix timestamp when the rate limit window resets

You can inspect these headers using browser developer tools or command-line tools like curl:

curl -I -H "Authorization: Bearer YOUR_TOKEN" http://your-patchmon-instance/api/v1/hosts

Error Response Format

When rate limited, the API returns a JSON response:

{
  "error": "Too many requests from this IP, please try again later.",
  "retryAfter": 900
}

The retryAfter field indicates how many seconds to wait before retrying.

Adjusting Rate Limits

For Docker Deployments

Method 1: Environment Variables in docker-compose.yml

Edit your docker-compose.yml file to add or modify rate limiting environment variables:

services:
  backend:
    image: ghcr.io/patchmon/patchmon-backend:latest
    environment:
      # General API rate limit
      RATE_LIMIT_WINDOW_MS: 900000
      RATE_LIMIT_MAX: 10000  # Increase from 5000 to 10000
      
      # Authentication rate limit
      AUTH_RATE_LIMIT_WINDOW_MS: 600000
      AUTH_RATE_LIMIT_MAX: 1000  # Increase from 500 to 1000
      
      # Agent API rate limit
      AGENT_RATE_LIMIT_WINDOW_MS: 60000
      AGENT_RATE_LIMIT_MAX: 5000  # Increase from 1000 to 5000
      
      # ... other environment variables

After modifying the file, restart the backend service:

docker compose restart backend

Method 2: Environment File

Alternatively, create a .env file and reference it in your compose file:

# .env file
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX=10000
AUTH_RATE_LIMIT_WINDOW_MS=600000
AUTH_RATE_LIMIT_MAX=1000
AGENT_RATE_LIMIT_WINDOW_MS=60000
AGENT_RATE_LIMIT_MAX=5000

Reference it in docker-compose.yml:

services:
  backend:
    env_file: .env
    # ... other configuration

For Native Deployments

If you're running PatchMon natively (without Docker), set the environment variables in your backend's .env file:

# backend/.env

# Rate Limiting (times in milliseconds)
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX=10000
AUTH_RATE_LIMIT_WINDOW_MS=600000
AUTH_RATE_LIMIT_MAX=1000
AGENT_RATE_LIMIT_WINDOW_MS=60000
AGENT_RATE_LIMIT_MAX=5000

Then restart your backend service:

# Using systemd
sudo systemctl restart patchmon-backend

# Or using PM2
pm2 restart patchmon-backend

Small Deployment (1-50 hosts)

The default settings are appropriate:

RATE_LIMIT_MAX: 5000
AUTH_RATE_LIMIT_MAX: 500
AGENT_RATE_LIMIT_MAX: 1000

Medium Deployment (51-200 hosts)

Increase agent limits:

RATE_LIMIT_MAX: 10000
AUTH_RATE_LIMIT_MAX: 1000
AGENT_RATE_LIMIT_MAX: 3000

Large Deployment (201-1000 hosts)

Significantly increase all limits:

RATE_LIMIT_MAX: 25000
AUTH_RATE_LIMIT_MAX: 2000
AGENT_RATE_LIMIT_MAX: 10000

Very Large Deployment (1000+ hosts)

Consider implementing a more sophisticated approach:

RATE_LIMIT_MAX: 50000
AUTH_RATE_LIMIT_MAX: 5000
AGENT_RATE_LIMIT_MAX: 25000

Best Practices

1. Monitor Your Usage

Regularly check your rate limit headers and application logs to understand your actual usage patterns. This helps you set appropriate limits.

2. Gradual Increases

When adjusting limits, increase them gradually and monitor the impact on system performance. Sudden large increases may impact server resources.

3. Consider Peak Times

Set limits based on peak usage times, not average usage. Account for:

  • Agent check-in schedules (if many agents report simultaneously)
  • User login times (e.g., start of business day)
  • Automated script executions

4. Load Balancing

For very large deployments, consider running multiple backend instances behind a load balancer, with each instance having its own rate limits.

5. Document Your Changes

Keep a record of rate limit changes and the reasons for them. This helps with troubleshooting and capacity planning.

Security Considerations

Do Not Disable Rate Limiting

Rate limiting is a critical security feature. Disabling it entirely (by setting extremely high limits) exposes your instance to:

  • Brute Force Attacks: Attackers attempting to guess passwords
  • DDoS Attacks: Overwhelming your server with requests
  • Resource Exhaustion: Excessive requests consuming server resources
  • API Abuse: Malicious or poorly configured clients hammering endpoints

Authentication Endpoints

Be especially careful with authentication rate limits (AUTH_RATE_LIMIT_MAX). Low limits here help prevent:

  • Password guessing attacks
  • Credential stuffing attempts
  • Session hijacking attempts

Recommendation: Only increase authentication limits if you have legitimate high-volume authentication needs.

Behind a Reverse Proxy

If PatchMon is behind a reverse proxy (nginx, Caddy, Apache, etc.):

  1. Ensure the TRUST_PROXY environment variable is correctly set
  2. The reverse proxy should pass the real client IP
  3. Consider implementing rate limiting at the reverse proxy level as an additional layer
TRUST_PROXY: true  # or specific proxy IPs

IP-Based Limiting

PatchMon's rate limiting is IP-based by default. This means:

  • Multiple users behind the same NAT/proxy share a rate limit
  • In office environments, all users may share limits
  • Consider this when setting limits for your deployment

Troubleshooting

Problem: Agents Consistently Hit Rate Limits

Symptoms: Agents fail to report, 429 errors in agent logs

Solutions:

  1. Increase AGENT_RATE_LIMIT_MAX
  2. Stagger agent check-in times
  3. Reduce agent reporting frequency
  4. Check for misconfigured agents sending excessive requests

Problem: Users Cannot Log In (429 on Auth Endpoints)

Symptoms: Login failures, authentication errors

Solutions:

  1. Check for brute force attacks in logs
  2. If legitimate traffic, increase AUTH_RATE_LIMIT_MAX
  3. Consider implementing IP whitelisting for trusted networks
  4. Check if automated scripts are hammering the auth endpoints

Problem: Dashboard API Calls Failing

Symptoms: Dashboard loading issues, 429 errors in browser console

Solutions:

  1. Increase RATE_LIMIT_MAX
  2. Check for inefficient frontend code making excessive requests
  3. Implement client-side caching
  4. Review polling intervals in the frontend

Problem: Rate Limits Reset Too Slowly

Symptoms: Users/agents locked out for extended periods

Solutions:

  1. Reduce *_WINDOW_MS values for faster reset
  2. Balance between security and usability
  3. Consider exponential backoff in clients

Monitoring and Alerting

Logs to Monitor

Watch for these patterns in your logs:

# Check for rate limit hits
docker compose logs backend | grep "Too many requests"

# Check which IPs are being rate limited
docker compose logs backend | grep "429"

Set Up Alerts

Consider setting up alerts when rate limiting occurs frequently:

  • High number of 429 responses (indicates limits too low or potential attack)
  • Specific users/agents consistently hitting limits
  • Sudden spikes in rate limit violations

Metrics to Track

  • Number of 429 responses per hour/day
  • Which endpoints are most rate-limited
  • Which IPs/users trigger rate limits
  • Average rate limit usage (via headers)

Additional Resources

Support

If you continue to experience rate limiting issues after following this guide:

  1. Check the GitHub Issues for similar problems
  2. Review your application logs for specific error patterns
  3. Open a new issue with:
    • Your deployment size (number of hosts/users)
    • Current rate limit settings
    • Frequency of 429 errors
    • Relevant log snippets

Last Updated: 22 October 2025
PatchMon Version: 1.3.0+

Back to top