AI HTTP Status Codes — The Complete Quick Reference Guide

Your API returns a 403. The frontend developer says it should be a 401. The product manager asks why users see a "forbidden" message when they are clearly logged in. Meanwhile, the load balancer is throwing 502s that have nothing to do with your code. HTTP status codes seem simple until you actually have to choose the right one — or debug the wrong one in production.

An HTTP status code reference tool gives you instant answers. Search by code number, filter by category, and see real-world examples of when each code applies. No more guessing whether you need a 301 or a 308.

The Five Categories of HTTP Status Codes

HTTP response codes are grouped into five classes based on their first digit. Understanding the categories helps you narrow down problems even before you look up the specific code.

1xx — Informational

These are provisional responses. The server received the request and is continuing to process it. You rarely see these in application code, but they matter for protocol-level operations:

• 100 Continue — the server received the request headers and the client should send the body. Used with large uploads when the client sends Expect: 100-continue.
• 101 Switching Protocols — the server is switching to a different protocol (usually WebSocket). You see this during the WebSocket handshake.
• 103 Early Hints — lets the browser preload resources before the final response arrives. Useful for performance optimization.

2xx — Success

The request was received, understood, and accepted. These are the codes you want to see:

• 200 OK — the standard success response. Use for GET requests that return data and PUT/PATCH requests that update resources.
• 201 Created — a new resource was created. Use for POST requests that create something. Include a Location header pointing to the new resource.
• 204 No Content — success, but there is nothing to return. Use for DELETE requests and updates where the client does not need the response body.
• 206 Partial Content — the server is returning part of the resource. Used for range requests (video streaming, resumable downloads).

3xx — Redirection

The client needs to take additional action to complete the request. Getting redirects right is critical for SEO and user experience:

• 301 Moved Permanently — the resource has a new permanent URL. Search engines transfer ranking to the new URL. Browsers cache this aggressively.
• 302 Found — temporary redirect. The original URL is still valid. Search engines keep indexing the original URL.
• 304 Not Modified — the resource has not changed since the last request. The client should use its cached copy. Saves bandwidth.
• 307 Temporary Redirect — like 302, but guarantees the HTTP method is preserved. A POST stays a POST.
• 308 Permanent Redirect — like 301, but guarantees the HTTP method is preserved.

4xx — Client Errors

The request contains an error on the client side. These are the codes that cause the most confusion:

• 400 Bad Request — the request is malformed. Missing required fields, invalid JSON, wrong content type. Always include a descriptive error message in the response body.
• 401 Unauthorized — authentication is required but missing or invalid. The name is misleading — it really means "unauthenticated." The client needs to log in.
• 403 Forbidden — the client is authenticated but does not have permission. This is the actual "unauthorized" code. The client is logged in but cannot access this resource.
• 404 Not Found — the resource does not exist. Also used to hide the existence of resources from unauthorized users (instead of 403).
• 405 Method Not Allowed — the HTTP method is not supported for this endpoint. A GET-only endpoint receiving a POST.
• 409 Conflict — the request conflicts with the current state. Duplicate entries, version conflicts, concurrent modifications.
• 422 Unprocessable Entity — the request is well-formed but semantically invalid. The JSON parses fine, but the email field contains "not-an-email."
• 429 Too Many Requests — rate limiting. Include a Retry-After header telling the client when to try again.

5xx — Server Errors

Something went wrong on the server side. These codes mean your code (or infrastructure) has a problem:

• 500 Internal Server Error — the generic "something broke" response. Unhandled exceptions, null pointer errors, database connection failures.
• 502 Bad Gateway — the server acting as a proxy received an invalid response from the upstream server. Common with Nginx in front of a crashed application.
• 503 Service Unavailable — the server is temporarily unable to handle requests. Maintenance mode, overloaded, or starting up. Include a Retry-After header.
• 504 Gateway Timeout — the proxy did not receive a timely response from the upstream server. Your application is too slow or hanging.

The 401 vs 403 Debate

This is the most commonly confused pair of HTTP status codes. Here is the definitive answer:

Use 401 when the client has not provided authentication credentials, or the credentials are invalid. The response should include a WWW-Authenticate header indicating the authentication scheme. The client can fix this by logging in.

Use 403 when the client is authenticated (you know who they are) but they do not have permission to access the resource. Re-authenticating will not help. They need different permissions.

// No token provided or token is invalid/expired
GET /api/admin/users
→ 401 Unauthorized
   WWW-Authenticate: Bearer

// Valid token, but user is not an admin
GET /api/admin/users
Authorization: Bearer valid-user-token
→ 403 Forbidden
   {"error": "Admin role required"}

Some APIs use 404 instead of 403 to avoid revealing that a resource exists. This is a valid security practice — if an attacker should not even know the endpoint exists, returning 404 is safer than 403.

Choosing the Right Status Code for Your REST API

A well-designed API uses status codes consistently. Here is a practical mapping for common CRUD operations:

POST   /users          → 201 Created (with Location header)
GET    /users           → 200 OK
GET    /users/123       → 200 OK (or 404 if not found)
PUT    /users/123       → 200 OK (or 204 No Content)
PATCH  /users/123       → 200 OK (or 204 No Content)
DELETE /users/123       → 204 No Content
POST   /users (dup)     → 409 Conflict
POST   /users (invalid) → 422 Unprocessable Entity

Consistency matters more than perfection. Pick a convention and stick with it across your entire API. Document your status code usage in your API documentation so consumers know what to expect.

Debugging HTTP Errors in Production

502 and 504 from Nginx

These are the most common production headaches. A 502 means Nginx connected to your application but got garbage back (or the connection was reset). A 504 means Nginx waited too long and gave up. Common causes:

• Application crashed or is not running
• Socket file or port mismatch between Nginx and the app
• Application is too slow (increase proxy_read_timeout as a temporary fix)
• Memory exhaustion causing OOM kills

Check your application logs first, not Nginx logs. The Nginx error log will say "upstream prematurely closed connection" which tells you nothing useful. Your application log will have the actual stack trace. Use DNS lookup tools to verify your domain is resolving correctly if the issue seems network-related.

Mysterious 403s

When you get 403s that your application code is not generating, check these in order: file permissions on static assets (use a chmod calculator to verify), directory listing disabled in Nginx, WAF or CDN rules blocking requests, CORS preflight failures (which actually return different codes but often get reported as 403).

Status Codes That Most Developers Never Use (But Should)

Beyond the common codes, several underused status codes can improve your API design:

• 202 Accepted — the request has been accepted for processing but is not complete. Perfect for async operations like report generation or batch imports.
• 206 Partial Content — essential for video streaming and large file downloads. Supports range requests so users can seek in videos.
• 409 Conflict — better than 400 for duplicate entries and optimistic locking failures. Tells the client exactly what went wrong.
• 410 Gone — the resource existed but has been permanently deleted. Better than 404 for SEO because search engines will remove the URL from their index.
• 429 Too Many Requests — proper rate limiting with a Retry-After header. Much better than returning 403 or 503 for rate limits.

Using precise status codes makes your API self-documenting. A client that receives a 429 with Retry-After: 60 knows exactly what to do without reading any documentation. Pair this with a solid JSON response format and your API becomes a pleasure to integrate with.

Related Tools for API Development

HTTP status codes are just one piece of the API puzzle. Here are other tools that complement your workflow:

• JWT Decoder — decode and verify authentication tokens when debugging 401 errors
• CORS Tester — debug cross-origin request issues that often masquerade as HTTP errors
• Hash Generator — generate checksums for API request verification
• SSL Certificate Checker — verify HTTPS configuration that can cause connection errors