📮 HTTP Methods & Status Codes

Anatomy of a Request & Response

Every HTTP exchange is a pair of plain-text messages. The client sends a request; the server sends back a response. Once you can read them, nothing about APIs feels mysterious.

Here is a request and its response, annotated:

GET /api/users/123 HTTP/1.1      <- method, path, protocol version
Host: example.com                <- which server
Accept: application/json         <- "I'd like JSON back, please"
Authorization: Bearer eyJhbGc... <- who I am (stateless auth)

HTTP/1.1 200 OK                  <- protocol, status code, reason phrase
Content-Type: application/json   <- the format of the body
Cache-Control: max-age=60        <- how long this may be cached

{ "id": 123, "name": "Ada Lovelace" }   <- the body (a representation)

A request has a method (the verb), a path (the resource), headers (metadata), and an optional body (data you're sending). A response has a status code (how it went), headers, and usually a body. The rest of this lesson is really just: pick the right method for the request, and the right status code for the response.

The HTTP Methods in Depth

GET — retrieve a resource

Safe and idempotent. A GET must never change server state; it only reads. Successful GETs return 200 OK with the resource in the body.

app.get('/api/users/:id', (req, res) => {
  const user = getUserById(req.params.id);
  if (!user) {
    return res.status(404).json({ error: 'Not Found', message: 'No such user' });
  }
  res.status(200).json(user);          // 200 + the representation
});

POST — create a resource

Not safe, not idempotent. POST submits data to a collection and the server creates a new member with a server-assigned id. Respond 201 Created and set a Location header pointing at the new resource.

app.post('/api/users', (req, res) => {
  const { name, email } = req.body;
  if (!name || !email) {
    return res.status(400).json({ error: 'Bad Request', message: 'name and email are required' });
  }
  if (getUserByEmail(email)) {
    return res.status(409).json({ error: 'Conflict', message: 'Email already registered' });
  }
  const user = createUser({ name, email });
  res.status(201)
     .location(`/api/users/${user.id}`)   // where to find the new resource
     .json(user);
});

PUT — replace a resource

Not safe, but idempotent. PUT sends the complete new representation; the server replaces the resource wholesale. Sending the same PUT twice yields the same final state — that's the idempotency.

app.put('/api/users/:id', (req, res) => {
  const { name, email, role } = req.body;
  if (!name || !email) {                 // PUT needs the FULL resource
    return res.status(400).json({ error: 'Bad Request', message: 'Complete representation required' });
  }
  if (!getUserById(req.params.id)) {
    return res.status(404).json({ error: 'Not Found' });
  }
  const user = replaceUser(req.params.id, { name, email, role });
  res.status(200).json(user);
});

PATCH — partially update a resource

Not safe; not necessarily idempotent. PATCH carries only the fields that change, leaving the rest untouched.

app.patch('/api/users/:id', (req, res) => {
  const existing = getUserById(req.params.id);
  if (!existing) return res.status(404).json({ error: 'Not Found' });

  const user = updateUser(req.params.id, req.body);  // merge only sent fields
  res.status(200).json(user);
});

DELETE — remove a resource

Not safe, but idempotent. On success, respond 204 No Content — the deletion happened and there's nothing left to send back.

app.delete('/api/users/:id', (req, res) => {
  if (!getUserById(req.params.id)) {
    return res.status(404).json({ error: 'Not Found' });
  }
  deleteUser(req.params.id);
  res.status(204).end();                 // 204 = success, empty body
});

PUT vs PATCH — the distinction that trips everyone up

Both update an existing resource, but they mean different things. PUT replaces; PATCH modifies. Send a PUT with only some fields and, strictly speaking, the missing fields should be wiped to their defaults — because you declared this to be the resource's complete new state.

Start with this user:

{ "id": 123, "name": "Ada Lovelace", "email": "ada@example.com", "role": "admin" }

Status Code Families

Status codes are three digits, and the first digit tells you the category. Memorize the five families and you can guess the meaning of a code you've never seen.

The Codes You'll Actually Use

There are dozens of status codes, but a REST API leans on about a dozen. Here they are, grouped, with when to reach for each.

2xx — Success

3xx — Redirection

4xx — Client Error

5xx — Server Error

Two representative handlers — a validation failure and a conflict:

// 422 — the JSON parsed fine, but the values break our rules
app.post('/api/users', (req, res) => {
  const { email, age } = req.body;
  const errors = [];
  if (age !== undefined && (age < 18 || age > 120)) {
    errors.push('age must be between 18 and 120');
  }
  if (email && !email.includes('@')) {
    errors.push('email format is invalid');
  }
  if (errors.length) {
    return res.status(422).json({
      error: 'Unprocessable Entity',
      message: 'Validation failed',
      details: errors
    });
  }
  // ...create the user
});

// 403 — authenticated, but not permitted
app.delete('/api/users/:id', (req, res) => {
  const me = req.user;                       // set by auth middleware
  if (me.role !== 'admin' && me.id !== req.params.id) {
    return res.status(403).json({
      error: 'Forbidden',
      message: 'You may only delete your own account'
    });
  }
  // ...delete
});

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "Unprocessable Entity",
  "message": "Validation failed",
  "details": ["age must be between 18 and 120"]
}

Designing Error Responses

A status code tells the client the category of failure; the body should tell it the specifics. Adopt one error shape and use it everywhere — consistency is what lets a client write a single error handler for your whole API.

// A consistent error envelope, reused across every endpoint
{
  "error": "Not Found",                     // short, machine-friendly title
  "message": "User with ID 123 not found",  // human-readable explanation
  "code": "USER_NOT_FOUND",                 // optional stable app-level code
  "details": [],                            // optional per-field errors
  "timestamp": "2026-07-31T12:34:56.000Z",  // when it happened
  "path": "/api/users/123"                  // which endpoint
}

Centralize it with Express error-handling middleware so individual routes stay clean:

// A custom error carrying its own status code
class ApiError extends Error {
  constructor(statusCode, message, details = []) {
    super(message);
    this.statusCode = statusCode;
    this.details = details;
  }
}

// Routes just throw — the middleware formats the response
app.get('/api/users/:id', (req, res, next) => {
  const user = getUserById(req.params.id);
  if (!user) return next(new ApiError(404, `User ${req.params.id} not found`));
  res.json(user);
});

// One error handler to shape them all (must have 4 args)
app.use((err, req, res, next) => {
  const status = err.statusCode || 500;
  if (status === 500) console.error(err);   // log the unexpected ones
  res.status(status).json({
    error: err.name || 'Error',
    message: status === 500 ? 'An unexpected error occurred' : err.message,
    details: err.details || [],
    timestamp: new Date().toISOString(),
    path: req.originalUrl
  });
});

Practice & Quiz

1. 201 Created           (new resource made)
2. 204 No Content        (success, empty body)
3. 401 Unauthorized      (not authenticated)
4. 403 Forbidden         (authenticated but not permitted)
5. 409 Conflict          (duplicate — conflicts with current state)
6. 422 Unprocessable Entity  (valid JSON, fails validation)

app.post('/api/articles', (req, res) => {
  const { title, slug } = req.body;
  // TODO 1: reject missing title with the right 4xx code
  // TODO 2: reject a duplicate slug with the right 4xx code
  // TODO 3: create the article and respond with the right 2xx code + Location
});

app.post('/api/articles', (req, res) => {
  const { title, slug } = req.body;

  if (!title) {
    return res.status(400).json({ error: 'Bad Request', message: 'title is required' });
  }
  if (getArticleBySlug(slug)) {
    return res.status(409).json({ error: 'Conflict', message: 'slug already in use' });
  }
  const article = createArticle({ title, slug });
  res.status(201)
     .location(`/api/articles/${article.id}`)
     .json(article);
});

Best Practices & Pitfalls

✅ Do

• Return 201 + Location on create, 204 on delete
• Keep GET safe — never mutate state in a GET handler
• Use 4xx for client mistakes, 5xx for server failures
• Ship a consistent error body across every endpoint
• Distinguish 401 (who are you?) from 403 (you can't)

❌ Don't

• Return 200 OK with {"error": ...} in the body — the status must reflect the outcome
• Use PUT to change a single field (that's PATCH)
• Send a stack trace or SQL in a 500 response
• Answer every failure with 400 — reach for 401/403/404/409/422 when they fit
• Forget the Location header after a 201

// ❌ Lies to the client — the request FAILED but the status says OK
res.status(200).json({ success: false, error: 'User not found' });

// ✅ The status code IS the outcome
res.status(404).json({ error: 'Not Found', message: 'User not found' });

Summary

📚 Additional Resources

• MDN — HTTP request methods
• MDN — HTTP response status codes
• restfulapi.net — HTTP Status Codes
• MDN — 422 Unprocessable Content

🚀 What's Next?

You now speak the verbs and the punctuation of HTTP. Next you'll put them to work at scale in API Endpoint Design — structuring resource URLs, nesting relationships, adding filtering, sorting, pagination, and versioning so a whole API stays consistent and predictable.