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[2]: You are diagnosing a 5xx response or deciding how clients should retry.,You are defining monitoring for server errors.
  caveats[2]: 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[4]: 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[9]{section,field,type,example}:
    server_errors,code,integer,"500"
    server_errors,name,string,Internal Server Error
    server_errors,cause,string,"Generic server-side error; unhandled exception,…"
    server_errors,diagnosis,string,"Check application logs, stack traces, error mon…"
    server_errors,client_action,string,Retry after delay (exponential backoff). If per…
    server_errors,server_fix,string,"Add error handling, validate inputs, ensure res…"
    server_errors,example,string,Method not implemented (POST on endpoint that o…
    retry_strategy,*,object,"{exponential_backoff,example_config,jitter,idempotency}"
    monitoring_metrics,*,array,"[5 items]"
data:
  server_errors[7]:
    - 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[5]: 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)