HTTP Methods and Status Codes

HTTP methods and status codes are the vocabulary every backend API speaks, regardless of language or framework. Getting them right — using the correct verb for an action, returning the correct code for an outcome — is what makes an API predictable to the clients that consume it.

The core methods

| Method | Purpose | Safe? | Idempotent? | |---|---|---|---| | GET | Retrieve a resource | Yes | Yes | | POST | Create a resource, or trigger an action | No | No | | PUT | Replace a resource entirely | No | Yes | | PATCH | Partially update a resource | No | No (usually) | | DELETE | Remove a resource | No | Yes |

"Safe" means the method doesn't change server state — a GET should never delete data. "Idempotent" means calling it multiple times with the same input produces the same end state as calling it once: sending the same PUT request three times leaves the resource exactly as it would be after one. POST is neither, which is why resubmitting a form that issues a POST (like a payment) can create duplicates if you're not careful — that's the origin of "don't double-click submit."

PUT /api/users/42 — replace user 42 entirely PATCH /api/users/42 — update just the fields provided DELETE /api/users/42 — remove user 42

Status code ranges

• 1xx — Informational, rarely seen directly (101 Switching Protocols).
• 2xx — Success. 200 OK (general success), 201 Created (a resource was created, typically after POST), 204 No Content (success, nothing to return).
• 3xx — Redirection. 301 Moved Permanently, 304 Not Modified (used with caching).
• 4xx — Client error — the request itself was wrong. 400 Bad Request (malformed input), 401 Unauthorized (not authenticated), 403 Forbidden (authenticated but not allowed), 404 Not Found, 409 Conflict (e.g. a duplicate), 422 Unprocessable Entity (well-formed but semantically invalid), 429 Too Many Requests.
• 5xx — Server error — something broke on the backend. 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable.

Why the distinction between 401 and 403 trips people up

401 Unauthorized actually means "I don't know who you are" — no valid credentials were presented. 403 Forbidden means "I know who you are, and you're not allowed to do this." A request with no auth token at all should return 401; a request from a logged-in user trying to access another user's private data should return 403. Conflating them makes API errors harder for clients to handle programmatically — a client typically responds to 401 by prompting login, and to 403 by showing a permissions error, which are very different user experiences.

Why this matters beyond correctness

Clients — whether a frontend app, a mobile client, or another backend — often branch on status codes to decide what to do next: retry on 503, refresh a token on 401, show a validation message on 422. Returning 200 OK with an error message buried in the body defeats that entirely, forcing every client to parse text instead of checking a status code.

With the vocabulary in place, the next lesson looks at how these methods and codes combine into a coherent style of API design: REST.