Tool

HTTP Status Troubleshooting Playbook

Follow a quick decision tree for 3xx, 4xx, and 5xx issues with common checks and fixes.

First 5 minutes triage

Scope: identify affected endpoints, regions, and clients.
Recent changes: review deploys, config updates, feature flags, and DNS/CDN changes.
Reproduce: use a curl request with a trace ID and capture headers, payload, and latency.
Dependencies: check upstream health, queue depth, and database saturation.
Mitigation: rollback or throttle if error rates spike.

Quick decision tree

Start with the status family and follow the checks. If the response is 2xx but behavior is wrong, check caching, data freshness, and client parsing.

3xx

3xx Redirects

Unexpected redirects, loops, or mixed cache behavior.

• Validate the Location header and protocol (http vs https).
• Confirm load balancer and CDN redirect rules are not overlapping.

4xx

4xx Client Errors

Auth issues, invalid payloads, or missing routes.

• Verify auth headers, tokens, and scopes.
• Confirm request validation and required fields.

5xx

5xx Server Errors

Unhandled exceptions, dependency failures, or timeouts.

• Inspect server logs for stack traces and error IDs.
• Check upstream dependency health and latency.

3xx Redirects

Unexpected redirects, loops, or mixed cache behavior.

Checks

• Validate the Location header and protocol (http vs https).
• Confirm load balancer and CDN redirect rules are not overlapping.
• Check for redirect loops with curl -I and follow redirects.

Fixes

• Remove duplicate redirect rules and normalize trailing slashes.
• Ensure canonical host redirect happens once.
• Align app and edge configs (HSTS, force-https) to avoid loops.

4xx Client Errors

Auth issues, invalid payloads, or missing routes.

Checks

• Verify auth headers, tokens, and scopes.
• Confirm request validation and required fields.
• Check route definitions, path params, and versioning.

Fixes

• Return clearer error messages for clients.
• Update API docs and SDKs with required fields.
• Add redirects or legacy route handling for old clients.

5xx Server Errors

Unhandled exceptions, dependency failures, or timeouts.

Checks

• Inspect server logs for stack traces and error IDs.
• Check upstream dependency health and latency.
• Review recent deploys, config changes, and feature flags.

Fixes

• Rollback or disable the recent change that introduced errors.
• Add retries, circuit breakers, or fallbacks for dependencies.
• Increase timeouts or capacity where saturation is visible.

Common status codes

400

Bad Request

Cause: Invalid JSON, missing fields, or bad query params.

Check: Compare request payload with schema; inspect validation logs.

Fix: Improve validation errors; update client payload or schema.

401

Unauthorized

Cause: Missing or expired credentials.

Check: Validate auth header, token expiry, and issuer.

Fix: Refresh tokens, fix auth header formatting, rotate keys.

403

Forbidden

Cause: Auth ok but insufficient permissions.

Check: Confirm roles/scopes on the token and policy rules.

Fix: Update policy mapping, roles, or scope list.

404

Not Found

Cause: Missing route or resource.

Check: Check routing table, trailing slash behavior, or IDs.

Fix: Add route, provide alias, or sync data between services.

409

Conflict

Cause: Concurrent write or duplicate resource.

Check: Review uniqueness constraints and idempotency keys.

Fix: Add idempotency, retries, or conflict resolution.

422

Unprocessable Entity

Cause: Semantically invalid request data.

Check: Inspect validation rules and input normalization.

Fix: Adjust schema, add client-side validation, return hints.

429

Too Many Requests

Cause: Rate limits or burst throttling.

Check: Review rate limit config, tokens, and edge policies.

Fix: Increase limits, implement backoff, cache responses.

500

Internal Server Error

Cause: Unhandled exception or unexpected state.

Check: Trace error IDs, stack traces, and recent deploys.

Fix: Fix crash path, add guardrails, and improve tests.

502

Bad Gateway

Cause: Upstream failed or misconfigured proxy.

Check: Inspect upstream health checks and proxy settings.

Fix: Fix upstream, increase retries, or adjust proxy routing.

503

Service Unavailable

Cause: Overloaded or in maintenance.

Check: Check autoscaling, queue depth, and maintenance flags.

Fix: Scale up, drain traffic, or disable maintenance mode.

504

Gateway Timeout

Cause: Upstream response exceeded timeout.

Check: Review latency, timeouts, and dependency saturation.

Fix: Increase timeout, optimize query, or add caching.