HTTP Status Codes

Also Known As

TL;DR

Explanation

HTTP status codes are grouped into five classes: 1xx (informational), 2xx (success), 3xx (redirection), 4xx (client error), and 5xx (server error). Using correct codes is essential for caching, retry logic, API clients, and debugging. A 200 OK with an error body, or a 500 for a validation failure, breaks every layer that depends on HTTP semantics.

Diagram

flowchart TD
    REQ[HTTP Request] --> RANGE{Status range}
    RANGE -->|1xx| INFO2[Informational<br/>100 Continue<br/>101 Switching Protocols]
    RANGE -->|2xx| SUCCESS[Success<br/>200 OK<br/>201 Created<br/>204 No Content]
    RANGE -->|3xx| REDIRECT[Redirect<br/>301 Permanent<br/>302 Temporary<br/>304 Not Modified]
    RANGE -->|4xx| CLIENT[Client Error<br/>400 Bad Request<br/>401 Unauthorized<br/>403 Forbidden<br/>404 Not Found<br/>422 Unprocessable<br/>429 Rate Limited]
    RANGE -->|5xx| SERVER[Server Error<br/>500 Internal Error<br/>502 Bad Gateway<br/>503 Service Unavailable]
style SUCCESS fill:#238636,color:#fff
style CLIENT fill:#f85149,color:#fff
style SERVER fill:#f85149,color:#fff
style REDIRECT fill:#d29922,color:#fff
style INFO2 fill:#1f6feb,color:#fff

Common Misconception

Why It Matters

Common Mistakes

• Returning 200 OK with an error body — clients cannot detect the failure without parsing every response.
• Using 500 for validation errors — 422 Unprocessable Entity or 400 Bad Request is correct for client-supplied bad data.
• Returning 404 for authorisation failures — use 403 Forbidden; 404 leaks that the resource exists.
• Not returning 429 Too Many Requests with a Retry-After header for rate-limited responses.

Code Examples

// 200 OK with error — breaks client error detection:
return response()->json(['error' => 'User not found'], 200); // Wrong

// Correct status codes:
return response()->json(['message' => 'Not found'], 404);
return response()->json(['errors' => $validation], 422);
return response()->json(['message' => 'Forbidden'], 403);

// Semantic status codes:
return response()->json($user, 200);          // GET success
return response()->json($created, 201);       // POST created
return response()->json(null, 204);           // DELETE success
return response()->json($errors, 422);        // Validation failed
return response()->json(['message' => 'Not found'], 404);

References

• ↗ https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
• ↗ https://www.rfc-editor.org/rfc/rfc9110

Tags

Related Terms