Catalog My learning Blog
API Design Course: REST and GraphQL Best Practices · Phase 1 · Lesson 4 · 3 min read

HTTP Methods and Status Codes for REST APIs

On this page
  1. Why every failure needs the right status code
  2. HTTP status codes you'll use most
  3. Example: one endpoint, four status codes
  4. 401 vs 403 vs 404
  5. Which status code each HTTP method returns
  6. Check yourself

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

CodeMeaningUse when
200 OKSuccess with a bodyGET, or an update returning the resource
201 CreatedA resource was createdPOST that creates; include a Location header
202 AcceptedAccepted, processing laterAsynchronous jobs; return a status URL
204 No ContentSuccess, no bodyDELETE, or updates that return nothing
304 Not ModifiedClient's cached copy is currentConditional GET (Day 5)
400 Bad RequestMalformed requestUnparseable JSON, wrong types
401 UnauthorizedNot authenticatedMissing, invalid or expired credentials
403 ForbiddenAuthenticated, not allowedMissing permission or scope
404 Not FoundNo such resource (or you may not know it exists)Unknown ID
409 ConflictConflicts with current stateDuplicate unique value, wrong state for the action
412 Precondition FailedConditional request failedStale If-Match ETag
422 Unprocessable ContentWell-formed but invalidValidation failures
429 Too Many RequestsRate limitedWith Retry-After (Day 11)
500 / 502 / 503 / 504Server-side failuresBugs, 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:

ResponseWhat the client should do
2xxUse the result
400, 401, 403, 404, 409, 422Don't retry as-is. Fix the request, sign in again, or show the user the problem
429, 503Wait for Retry-After, then retry
500, 502, 504, or no responseRetry with backoff, but only if the request is safe to repeat (Day 10)
Status code families: 2xx success, 3xx redirection and caching, 4xx client errors the caller must fix, 5xx server failures that may be retried.
Status code families: 2xx success, 3xx redirection and caching, 4xx client errors the caller must fix, 5xx server failures that may be retried.

Example: one endpoint, four status codes

POST /users from a small Express API, run with curl:

Code
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-Authenticate header. 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).
  • POST creating → 201 with Location; POST starting 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.