HTTP Methods and Status Codes for REST APIs
On this page
Why every failure needs the right status code
Some APIs return 200 OK with {"success": false} in the body. Every client must parse the body to learn that a request failed, monitoring counts failures as successes, and retry logic can't tell what's safe to repeat. HTTP status codes exist so clients can act on the outcome immediately.
HTTP status codes you'll use most
| Code | Meaning | Use when |
|---|---|---|
| 200 OK | Success with a body | GET, or an update returning the resource |
| 201 Created | A resource was created | POST that creates; include a Location header |
| 202 Accepted | Accepted, processing later | Asynchronous jobs; return a status URL |
| 204 No Content | Success, no body | DELETE, or updates that return nothing |
| 304 Not Modified | Client's cached copy is current | Conditional GET (Day 5) |
| 400 Bad Request | Malformed request | Unparseable JSON, wrong types |
| 401 Unauthorized | Not authenticated | Missing, invalid or expired credentials |
| 403 Forbidden | Authenticated, not allowed | Missing permission or scope |
| 404 Not Found | No such resource (or you may not know it exists) | Unknown ID |
| 409 Conflict | Conflicts with current state | Duplicate unique value, wrong state for the action |
| 412 Precondition Failed | Conditional request failed | Stale If-Match ETag |
| 422 Unprocessable Content | Well-formed but invalid | Validation failures |
| 429 Too Many Requests | Rate limited | With Retry-After (Day 11) |
| 500 / 502 / 503 / 504 | Server-side failures | Bugs, bad upstream, overload, upstream timeout |
The split that matters most: 4xx means the client should change something; 5xx means the server failed, and the same request may work later.
That split decides what a well-behaved client does next:
| Response | What the client should do |
|---|---|
| 2xx | Use the result |
| 400, 401, 403, 404, 409, 422 | Don't retry as-is. Fix the request, sign in again, or show the user the problem |
| 429, 503 | Wait for Retry-After, then retry |
| 500, 502, 504, or no response | Retry with backoff, but only if the request is safe to repeat (Day 10) |
Example: one endpoint, four status codes
POST /users from a small Express API, run with curl:
POST /users {"email":"a@b.com","password":"correct horse battery"}
HTTP/1.1 201 Created
Location: /users/9931
{"id":9931,"email":"a@b.com"}
POST /users {"email":"c@d.com","password":"short"}
HTTP/1.1 422 Unprocessable Entity
{"type":"https://api.example.com/errors/validation-error","title":"Request failed validation",
"status":422,"errors":[{"field":"password","message":"must be at least 12 characters"}]}
POST /users {"email":"a@b.com","password":"another long password"}
HTTP/1.1 409 Conflict
{"type":"https://api.example.com/errors/conflict","title":"Email already registered","status":409}
POST /users {bad json
HTTP/1.1 400 Bad Request
{"type":"https://api.example.com/errors/malformed-json","title":"Request body is not valid JSON","status":400}Each code tells the client what to do: 201 (store the new ID), 422 (show field errors), 409 (suggest signing in), 400 (a bug in the client). The bodies use the problem details format covered on Day 8.
The status line says 422 Unprocessable Entity while the table says Unprocessable Content. Same code: RFC 9110 renamed it in 2022, and Express still prints the old phrase. Clients act on the number, never the phrase.
400 versus 422 is a common debate. A practical rule: 400 when the request can't be parsed or has the wrong shape, 422 when it parsed fine but breaks validation rules. Whatever you pick, be consistent.
401 vs 403 vs 404
- 401: "Who are you?" Credentials are missing or invalid. Include a
WWW-Authenticateheader. The official name, Unauthorized, is misleading: 401 really means unauthenticated. - 403: "I know who you are, and you can't do this."
- 404 to hide existence: for another user's private resource, returning 404 instead of 403 avoids confirming that ID exists (Day 13).
Which status code each HTTP method returns
GET→ 200 (or 304, 404).POSTcreating → 201 withLocation;POSTstarting a job → 202.PUT/PATCH→ 200 with the updated resource, or 204.DELETE→ 204; deleting something already gone can return 204 or 404, but document which.
Check yourself
Clients, monitoring and retry logic can't tell success from failure without parsing every body; the status code should say what happened.
Often 404, so the API doesn't reveal that the document exists at all, which matters when ids can be guessed. 403 is acceptable when the document's existence isn't sensitive and telling the user they lack access is more helpful.
A Location header with the new resource's URL, and usually the created resource in the body, including server-generated fields like id and createdAt, so the client doesn't need a second request.
The 503, after waiting for Retry-After. A 422 means the data broke validation, so sending it again will fail the same way.
When the request was accepted for processing that hasn't finished, such as a long export. Return a URL where the client can check the job's status.