api: YAML JSON TOON Database version: 1.0.0 format: json dataset: id: 24 slug: http-server-error-guide title: HTTP Server Error Status Codes (5xx) description: "Guide to 5xx server error responses: diagnosing 500, 502, 503, 504 errors, retry strategies, and monitoring." summary: A guide to 5xx server-error codes (500, 501, 502, 503, 504, 507 and 511) with causes, diagnosis steps, what a client should do and what a server owner should fix, plus a retry strategy and monitoring metrics. use_when: - You are diagnosing a 5xx response or deciding how clients should retry. - You are defining monitoring for server errors. caveats: - 5xx codes do not say whether a request had effects; retry only idempotent requests or use idempotency keys. - Retries without backoff and jitter can turn a partial outage into a full one. related: - http-client-error-guide - http-status-codes-complete - site-reliability-practices - monitoring-logging-tools category: HTTP Status Codes category_slug: http-status-codes tags: http,server-errors,5xx,monitoring,retry,devops view_count: 0 created_at: 1777673262 updated_at: 1777673262 entry_count: 12 fields: - section: server_errors field: code type: integer example: "500" - section: server_errors field: name type: string example: Internal Server Error - section: server_errors field: cause type: string example: Generic server-side error; unhandled exception,… - section: server_errors field: diagnosis type: string example: Check application logs, stack traces, error mon… - section: server_errors field: client_action type: string example: Retry after delay (exponential backoff). If per… - section: server_errors field: server_fix type: string example: Add error handling, validate inputs, ensure res… - section: server_errors field: example type: string example: Method not implemented (POST on endpoint that o… - section: retry_strategy field: "*" type: object example: "{exponential_backoff,example_config,jitter,idempotency}" - section: monitoring_metrics field: "*" type: array example: "[5 items]" data: server_errors: - code: 500 name: Internal Server Error cause: Generic server-side error; unhandled exception, unexpected condition. diagnosis: "Check application logs, stack traces, error monitoring (Sentry, Datadog). Common causes: null pointer, DB connection failure, unhandled promise rejection." client_action: Retry after delay (exponential backoff). If persists, contact support with request ID/timestamp. server_fix: Add error handling, validate inputs, ensure resources available, catch exceptions - code: 501 name: Not Implemented cause: Server does not support the functionality required to fulfill the request. example: Method not implemented (POST on endpoint that only supports GET), feature flag disabled diagnosis: Check API documentation; endpoint may be planned but not released client_action: Use alternative endpoint or method; check docs for supported operations - code: 502 name: Bad Gateway cause: Server acting as gateway/proxy received invalid response from upstream server. example: Nginx proxy to PHP-FPM got malformed response, API gateway to microservice got 404/invalid JSON diagnosis: Check upstream service health, connectivity, response format; inspect proxy logs client_action: Retry after short delay (upstream may be temporary); if persistent, contact API provider - code: 503 name: Service Unavailable cause: Server temporarily unable to handle request due to overload or maintenance. example: Too many concurrent connections, server restarting, maintenance mode, auto-scaling cold start diagnosis: Check server load (CPU/memory), connection pool exhaustion, deployment status client_action: Retry with exponential backoff (e.g., 1s, 2s, 4s, 8s); check status page for known outage server_fix: Scale resources, enable connection queuing, implement graceful degradation, schedule maintenance windows - code: 504 name: Gateway Timeout cause: Gateway/proxy did not receive timely response from upstream server. example: Nginx proxy timeout after 60s, API gateway upstream slow query (>30s), slow third-party API diagnosis: Check upstream service latency, database query performance, network connectivity, timeout configurations client_action: Retry with longer delay (upstream may need recovery); consider breaking request into smaller chunks - code: 507 name: Insufficient Storage cause: Server unable to store representation (disk full, quota exceeded). example: Upload fails because disk full, user storage quota exceeded, temp directory full diagnosis: Check disk space (`df -h`), inode usage, storage quotas, cleanup old files server_fix: Increase storage, implement cleanup policies, add monitoring alerts for disk space - code: 511 name: Network Authentication Required cause: Client needs to authenticate to gain network access (captive portal, proxy auth). example: Wi-Fi hotspot login page, corporate proxy requiring credentials diagnosis: Check if behind captive portal; client should redirect user to login page client_action: Open browser to authenticate; client libraries should handle 511 by showing login URL retry_strategy: exponential_backoff: Wait = min(2^n * base, max_delay) where n = attempt number (starting at 0) example_config: initial_delay_ms: 1000 max_delay_ms: 60000 multiplier: 2 max_retries: 5 jitter: Add random ±10-25% to prevent thundering herd idempotency: Only retry idempotent methods (GET, PUT, DELETE, HEAD, OPTIONS); POST should be retried only with idempotency key monitoring_metrics: - Error rate percentage (5xx / total requests) - P99/P95 latency of error responses - Upstream service health checks - Server resource metrics (CPU, memory, disk, connections) - Circuit breaker state (open/closed/half-open)