WebGroundwebground.app
Info & Guides · Web Reference

HTTP Status Codes & Debugging Reference

Searchable cheat sheet for 1xx–5xx HTTP response status codes, meanings, and practical API & CDN debugging tips.

Showing 26 codes
100

Continue

Initial request headers were received; the client may send the request body.

Tip: Common when sending large payloads with an Expect: 100-continue header.

101

Switching Protocols

Server agreed to upgrade the connection, most commonly from HTTP to WebSocket.

Tip: Check Upgrade and Connection headers if a WebSocket handshake stalls.

200

OK

Standard response confirming the HTTP request succeeded.

Tip: Check response Content-Type and JSON structure if the client still fails to render.

201

Created

Request succeeded and created one or more new resources.

Tip: REST APIs typically include a Location header pointing to the new resource URL.

204

No Content

Request succeeded, and the server intentionally returned an empty body.

Tip: Avoid calling response.json() on 204 responses (common on DELETE or CORS OPTIONS).

206

Partial Content

Server delivered only the requested byte range of a file.

Tip: Used by video streaming players and resumable file downloads via Range headers.

301

Moved Permanently

Resource has permanently moved to a new URL; search engines transfer SEO equity.

Tip: Browsers cache 301 redirects aggressively—test new rules in incognito or curl -I.

302

Found (Temporary Redirect)

Resource is temporarily served from another URL; keep original URL indexed.

Tip: Often used during OAuth login flows or temporary maintenance routing.

304

Not Modified

Cached copy is still valid based on ETag or Last-Modified headers.

Tip: Saves bandwidth on static assets; verify Cache-Control headers if stale files persist.

307

Temporary Redirect

Temporary redirect that strictly preserves the original HTTP method and body.

Tip: Use 307 instead of 302 when a POST request must remain a POST after redirection.

308

Permanent Redirect

Permanent redirect that strictly preserves the original HTTP method and body.

Tip: Commonly used by Next.js trailing-slash redirects and HTTPS canonicalization.

400

Bad Request

Server could not process the request due to malformed syntax or invalid parameters.

Tip: Validate JSON formatting, required query fields, and Content-Type header.

401

Unauthorized

Authentication is missing, expired, or invalid for the requested endpoint.

Tip: Check Authorization Bearer token expiration, API key prefix, or session cookies.

403

Forbidden

Client identity is known (or blocked by policy), but lacks permission to access.

Tip: Check RBAC roles, CORS/WAF rules, or file/bucket permissions.

404

Not Found

Server cannot find the requested route or resource.

Tip: Verify trailing slashes, base path, DNS routing, or deleted resource IDs.

405

Method Not Allowed

The endpoint exists, but does not support the HTTP verb used (e.g., GET vs POST).

Tip: Inspect the Allow response header to see which HTTP methods are accepted.

408

Request Timeout

Client took too long to finish sending the request before the server closed the socket.

Tip: Check slow mobile uploads or keep-alive connection pooling mismatches.

409

Conflict

Request conflicts with the current state of the target resource.

Tip: Common on duplicate email registration or optimistic locking ETag mismatches.

413

Content Too Large

Request payload exceeds the server or reverse proxy size limit.

Tip: Compress images client-side before upload or raise proxy body-size limits.

415

Unsupported Media Type

Server refuses the payload format specified in Content-Type.

Tip: Ensure Content-Type: application/json or multipart/form-data matches the body.

422

Unprocessable Content

Syntax is valid (e.g., valid JSON), but field values failed semantic validation.

Tip: Inspect error details for invalid email formats, negative quantities, or missing enums.

429

Too Many Requests

Client exceeded the API rate limit or burst quota.

Tip: Respect the Retry-After header and add exponential backoff with jitter.

500

Internal Server Error

Unexpected unhandled exception occurred on the origin server.

Tip: Check origin server stack traces, missing env variables, or database crashes.

502

Bad Gateway

Proxy, CDN, or load balancer received an invalid response from the upstream server.

Tip: Verify the upstream app process is running and listening on the expected port.

503

Service Unavailable

Server is temporarily overloaded or down for scheduled maintenance.

Tip: Look for Retry-After headers, health-check failures, or cold-start exhaustion.

504

Gateway Timeout

Proxy or CDN timed out waiting for the upstream server to respond.

Tip: Optimize slow database queries or move long jobs to async background queues.

Debugging a 400 Bad Request or API JSON payload right now?Open JSON Formatter

Understanding the Five HTTP Status Code Classes

Every HTTP response begins with a three-digit status code defined by RFC 9110. Grouping codes by their leading digit lets developers, DevOps engineers, and SEO specialists diagnose issues in seconds.

Broadly, 1xx codes signal protocol handshakes, 2xx codes confirm success, 3xx codes indicate caching or URL redirection, 4xx codes point to client-side request issues, and 5xx codes signal origin or upstream server failures.

Common Status Code Traps in Production

Knowing the subtle differences between adjacent status codes prevents hard-to-trace bugs:

  • 401 Unauthorized vs. 403 Forbidden: 401 means missing or invalid credentials (re-authenticate), while 403 means authenticated or recognized clients lack permission.
  • 301/302 vs. 307/308: Legacy 301/302 redirects can silently convert POST requests to GET, whereas 307 and 308 preserve the original HTTP method.
  • 502 Bad Gateway vs. 504 Gateway Timeout: 502 indicates an invalid response from the upstream process, while 504 means the upstream server took too long to reply.

Frequently Asked Questions

What is the difference between 401 and 403?+

401 Unauthorized indicates missing, expired, or invalid authentication credentials. 403 Forbidden means the server understands who is calling (or blocks by policy) and refuses authorization.

How should clients handle 429 Too Many Requests?+

Inspect the Retry-After response header when present and retry using exponential backoff with random jitter to avoid synchronized retry storms.

Why does 204 No Content break response.json() in JavaScript?+

Because 204 responses intentionally contain an empty body, calling response.json() fails with an unexpected end-of-input error. Check response.status === 204 before parsing.

Explore More on WebGround

View all