HTTP Status Code Errors

Understanding HTTP errors

HTTP status codes are a first classification, not a diagnosis. The essential split: 4xx means the request was wrong (fix the client), 5xx means the server failed to fulfil a valid request (fix the server). The subtlety is that reverse proxies and CDNs generate their own 5xx responses. A 502 or 504 from nginx tells you about nginx's relationship with the upstream, not about your application code.

How to debug HTTP errors

1. Capture the full exchange with curl -v or curl -sD - -o /dev/null. Response headers frequently name the component that generated the error (Server:, Via:, X-Cache:).
2. Determine whether the response came from your application or from something in front of it. Add a unique header in your app and check whether it survives; if it is missing, a proxy answered.
3. For 502/504, check the upstream directly, bypassing the proxy. If the upstream is healthy, the problem is proxy timeouts, buffer sizes, or DNS re-resolution.
4. Follow redirects explicitly with curl -IL to catch loops. A redirect loop is usually an HTTPS-terminating proxy that does not forward X-Forwarded-Proto.
5. Correlate the request with server logs using a request ID. Guessing from the status code alone is the slowest way to debug HTTP.

Tools worth reaching for

• curl -v / -IL
• browser devtools Network tab
• access logs
• tcpdump / Wireshark
• httpstat

All 49 HTTP errors

• 100-continue timeout / Expect: 100-continue stallsThe client sent Expect: 100-continue and is waiting before streaming the body, but the proxy or server does not handle…
• 400 Bad RequestThe server could not parse the request due to malformed syntax: bad JSON body, illegal headers/characters, oversized…
• 401 UnauthorizedThe request requires authentication credentials. The client must authenticate to get the requested response.
• 402 Payment Required NewReserved in the original HTTP specification and now used by many SaaS APIs to signal that the account is unpaid, out…
• 403 ForbiddenThe server understood the request but refuses to authorise it. Often due to insufficient permissions.
• 404 Not FoundThe requested resource could not be found on the server. URL may be incorrect or resource was moved/deleted.
• 409 ConflictThe request conflicts with the current resource state. Typical causes include duplicate creates, optimistic locking…
• 410 GoneThe resource was intentionally removed and is not expected to return. Unlike 404, 410 tells clients and crawlers the…
• 421 Misdirected Request NewThe server received a request for a host it cannot serve on that connection. With HTTP/2 connection coalescing, a…
• 422 Unprocessable EntityThe request body is syntactically valid but semantically invalid. APIs commonly return this for validation errors such…
• 425 Too EarlyThe server refuses to process a request that might be replayed, typically TLS 1.3 0-RTT early data on a non-idempotent…
• 426 Upgrade RequiredThe server refuses to process the request using the current protocol and requires the client to switch (e.g., to TLS…
• 428 Precondition Required NewThe server requires the request to be conditional. It is telling the client to send If-Match or If-Unmodified-Since so…
• 429 Too Many RequestsThe client sent too many requests in a given window and was rate limited. The Retry-After header, if present, says how…
• 431 Request Header Fields Too Large NewThe combined size of the request headers exceeded the server's limit. In practice this is nearly always cookies: an…
• 451 Unavailable For Legal ReasonsThe resource is blocked for legal reasons such as censorship or a takedown. The response should reference the blocking…
• 500 Internal Server ErrorThe server encountered an unexpected condition that prevented it from fulfilling the request.
• 502 Bad GatewayThe server received an invalid response from an upstream service. Usually indicates the backend server is down or…
• 503 Service UnavailableThe server is temporarily unable to handle requests, often due to maintenance or overload.
• 504 Gateway TimeoutThe server didn't receive a timely response from an upstream server while acting as a gateway or proxy.
• 511 Network Authentication Required NewA captive portal (hotel, airport or corporate guest Wi-Fi) is intercepting traffic and requires sign-in. The response…
• API rate limit exceeded (global)Global API rate limit exceeded across all endpoints or users, temporary throttling in effect.
• API version mismatchClient is using an incompatible API version that the server no longer supports.
• Chunk encoding errorError in HTTP chunked transfer encoding, often due to incomplete or malformed chunks.
• Compression bomb detectedMalicious compressed content detected that could cause resource exhaustion when decompressed.
• Content encoding errorServer sent compressed content but client couldn't decode it, or encoding header mismatch.
• Content-Length mismatchThe actual content size doesn't match the Content-Length header value.
• Content-Type mismatchThe Content-Type header doesn't match the actual content being sent or expected by the server.
• CSRF token mismatchCross-Site Request Forgery protection rejected the request due to invalid or missing token.
• Duplicate header errorMultiple instances of the same HTTP header found, violating protocol specification.
• Expectation failedServer cannot meet the requirements specified in the Expect request header field.
• Geographic blockingRequest blocked due to geographic restrictions based on client IP address location.
• HTTP header too largeRequest or response headers exceed the server's configured maximum header size limit.
• HTTP pipelining errorError in HTTP pipelining where multiple requests are sent before receiving responses.
• HTTP request smuggling detectedPotential HTTP request smuggling attack detected, request blocked for security.
• HTTP version not supportedServer doesn't support the HTTP protocol version used in the request.
• HTTP/2 protocol errorError in HTTP/2 protocol handling, often due to server configuration or unsupported features.
• Insufficient storageServer cannot store the representation needed to complete the request due to lack of storage space.
• Invalid response headersServer sent malformed HTTP headers that the client couldn't parse properly.
• Keep-alive timeoutHTTP keep-alive connection timed out, server closed the persistent connection.
• Method not allowedThe HTTP method used in the request is not supported for the requested resource.
• OAuth insufficient scopeOAuth token doesn't have the required scope/permissions to access the requested resource.
• OAuth invalid tokenThe OAuth access token is expired, malformed, or doesn't have sufficient permissions.
• Payload too largeThe request payload exceeds the server's size limits for processing.
• Rate limit exceededToo many requests sent in a given time period. API or server has request rate limiting enabled.
• Request timeoutServer timed out waiting for the client to complete the request within the allowed time limit.
• Session expiredUser session has expired and needs to be renewed, often returning 401 or redirect to login.
• Too many redirectsThe request is stuck in an infinite redirect loop, often caused by misconfigured redirect rules.
• Unsupported media typeThe server doesn't support the media type of the request payload.

Other categories

• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Ansible 10Unreachable hosts, become passwords, undefined variables and Jinja2 failures.
• API 14Auth headers, payload limits, versioning, idempotency and webhook signatures.
• Apple 10Command line tools, dyld, Homebrew permissions, notarisation and Keychain.
• Auth 11OIDC, SAML, Auth0, Okta, Keycloak, passkeys and MFA failures.
• BigData 11Spark, Kafka, Airflow, Snowflake, Flink and Databricks failures.
• C# 12NuGet restore, null references, EF Core migrations, async deadlocks and Blazor…
• C++ 11Segfaults, linker errors, memory corruption and template deduction failures.
• Caching 10Cache stampedes, stale content, Varnish and CloudFront failures.
• CI/CD 18GitHub Actions, GitLab CI, Jenkins, CircleCI: permissions, runners and…
• Client 21CORS, mixed content, module resolution, memory limits and framework runtime…
• Cloud 25IAM permissions, quotas, service limits and credential failures.
• Dart 10Null safety, pub version solving and build toolchain problems.
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• DNS 10NXDOMAIN, SERVFAIL, timeouts, propagation and delegation problems.
• Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
• Elixir 9GenServer timeouts, supervision failures and Mix compilation problems.
• Email 8Delivery failures, relay denial, authentication, SPF, DKIM and DMARC.
• Frontend 23Hydration mismatches, bundler resolution, layout shift and font loading.
• Git 20Merge conflicts, rejected pushes, detached HEAD, LFS and repository corruption.
• Go 19Nil map assignment, concurrent map access, context cancellation and deadlocks.
• GraphQL 13Validation, depth limits, N+1 queries and fragment problems.
• gRPC 10Status codes, deadlines, message limits, TLS and HTTP/2 transport failures.
• ICMP 23Destination unreachable, time exceeded, fragmentation needed and redirects.
• Ingress 8404 default backend, missing TLS secrets, IngressClass and path matching.
• Java 19Class loading, dependency resolution, connection pools and JVM version…
• JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• Logging 9Log4j, Logback, Fluentd, Logstash and CloudWatch ingestion problems.
• MessageQueue 14Kafka, RabbitMQ, SQS, NATS and Celery: lag, rebalancing and poison messages.
• Mobile 17Gradle, CocoaPods, Xcode signing, Metro bundler and toolchain mismatches.
• Monitoring 12Prometheus scrapes, Grafana data sources, OpenTelemetry exporters and agent…
• Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
• Performance 6GC pauses, thread pool starvation and event loop blocking.
• PHP 11Memory limits, execution timeouts, autoloading, Composer and PDO connections.
• Proxy 17nginx, Envoy, HAProxy, Traefik, Caddy and Cloudflare upstream failures.
• Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
• Regex 8Catastrophic backtracking, back references, escaping and engine differences.
• Ruby 11Bundler, migrations, native extensions, encoding and asset compilation.
• Rust 19Borrow checker, ownership moves, trait bounds and lifetime mismatches.
• Scala 6Dependency resolution, binary compatibility and type inference failures.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• Serverless 11Lambda timeouts, package size limits, VPC networking and cold starts.
• Shell 13Command not found, permissions, quoting, expansion and Makefile syntax.
• Storage 13S3 permissions, NFS mounts, quotas, signed URLs and volume attachment.
• Svelte 10Store subscriptions, load functions and server/client boundaries.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Terraform 18State locks, provider auth, drift, dependency cycles and plan-time unknowns.
• Testing 18Jest, pytest, JUnit, Cypress and Playwright: fixtures, snapshots and timeouts.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.
• TypeScript 19Assignability, missing declarations, strict null checks and generic constraints.
• Virtualization 8VirtualBox, VMware, Hyper-V, WSL, KVM and hypervisor conflicts.
• Web3 7Gas estimation, nonce management and reverted transactions.
• WebAssembly 7Compile errors, memory bounds and host binding mismatches.
• WebServer 10nginx, Apache, IIS and Caddy: binding, permissions, rewrites and TLS.
• Windows 10Installer failures, missing runtimes, update errors and permission problems.