concept

HTTP Status Codes

What the common 2xx, 4xx, and 5xx response codes mean and when to use them

Overview

Status codes are three-digit numbers the server sends back to describe the outcome of a request. They're grouped by the first digit: 2xx means success, 3xx redirection, 4xx a client error, and 5xx a server error. Using the right code lets clients react correctly without parsing the response body.

Syntax / Usage

The status line appears at the top of every HTTP response. Pick the most specific code that fits the situation.

200 OK                     # request succeeded
201 Created                # new resource created
204 No Content             # success, nothing to return
400 Bad Request            # malformed or invalid input
401 Unauthorized           # missing/invalid credentials
403 Forbidden              # authenticated but not allowed
404 Not Found              # resource does not exist
409 Conflict               # state conflict (e.g. duplicate)
500 Internal Server Error  # unexpected server failure

Examples

A successful creation returns 201 with the new resource:

POST /orders HTTP/1.1

HTTP/1.1 201 Created
Location: /orders/1001
Content-Type: application/json

{ "id": 1001, "status": "pending" }

A request for something that doesn't exist returns 404:

GET /orders/9999 HTTP/1.1

HTTP/1.1 404 Not Found
Content-Type: application/json

{ "error": "Order not found" }

Common Mistakes

  • Returning 200 OK for errors and hiding the failure in the body
  • Using 401 Unauthorized when you mean 403 Forbidden (permissions)
  • Returning 500 for validation errors that are really 400
  • Using 200 for a creation instead of 201
  • Forgetting 204 No Content for successful deletes with no body

See Also

api-design-rest-basics api-design-http-methods api-design-error-handling