Understanding HTTP Methods and Status Codes

You call an API, the request "works", and the response is 200 OK with {"success": false} in the body. Your error handling never fires because it only checks response.ok. Or a form submit retries on a flaky connection and you end up with two orders in the database. Both bugs come from treating HTTP methods and status codes as details instead of a contract between client and server.

This post goes through the methods you'll actually use (GET, POST, PUT, PATCH, DELETE, plus HEAD and OPTIONS), what safe and idempotent mean in practice, the status codes worth knowing in each range, and a small Express API with a client that handles the responses properly.

The HTTP Request-Response Cycle

Every HTTP interaction involves a request from the client and a response from the server. The method tells the server what action to perform, and the status code tells the client what happened.

HTTP Methods Explained

The method (people often call it the "verb") says what you want done to the resource at that URL. HTTP defines a handful more, but these five cover nearly every API you'll build:

GET - Retrieve Data

// JavaScript Fetch API
const response = await fetch('/api/users');
const users = await response.json();

// With query parameters
const response = await fetch('/api/users?page=1&limit=10');

// Get single resource
const user = await fetch('/api/users/123');

// cURL
curl -X GET "https://api.example.com/users" -H "Accept: application/json"

POST - Create Data

// JavaScript Fetch API - Create a user
const response = await fetch('/api/users', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        name: 'John Doe',
        email: 'john@example.com'
    })
});

const newUser = await response.json();
// Response: { id: 124, name: 'John Doe', email: 'john@example.com' }

// cURL
curl -X POST "https://api.example.com/users" \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"john@example.com"}'

PUT - Replace Data

// Replace entire user resource
const response = await fetch('/api/users/123', {
    method: 'PUT',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        id: 123,
        name: 'John Updated',
        email: 'john.updated@example.com',
        role: 'admin'  // Must include ALL fields
    })
});

PATCH - Partial Update

// Update only the email field
const response = await fetch('/api/users/123', {
    method: 'PATCH',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        email: 'new.email@example.com'  // Only send what changes
    })
});

DELETE - Remove Data

// Delete a user
const response = await fetch('/api/users/123', {
    method: 'DELETE'
});

if (response.status === 204) {
    console.log('User deleted successfully');
}

// cURL
curl -X DELETE "https://api.example.com/users/123"

Other HTTP Methods

curl -I "https://api.example.com/users/123"

curl -X OPTIONS "https://api.example.com/users" -i
# Response Header: Allow: GET, POST, PUT, DELETE, OPTIONS

Method Properties Comparison

These three properties decide what caches, proxies and retry logic are allowed to do with a request, so they matter more than the names:

HTTP Status Codes Decoded

The first digit tells you who has to act. 2xx means it worked, 3xx means look elsewhere, 4xx means the client sent something wrong, and 5xx means the server broke. If you only remember one thing about status codes, make it that.

2xx Success Codes

3xx Redirection Codes

4xx Client Error Codes

5xx Server Error Codes

RESTful API Design Patterns

Here's how methods and codes line up for a typical users resource. Notice the URLs stay the same and only the method changes:

// Standard REST endpoints for a Users resource

GET    /api/users          → 200 OK (list all users)
GET    /api/users/123      → 200 OK (get single user) | 404 Not Found
POST   /api/users          → 201 Created (create user) | 400/422 (validation error)
PUT    /api/users/123      → 200 OK (replace user) | 404 Not Found
PATCH  /api/users/123      → 200 OK (update fields) | 404 Not Found
DELETE /api/users/123      → 204 No Content (deleted) | 404 Not Found

// Nested resources
GET    /api/users/123/posts       → 200 OK (user's posts)
POST   /api/users/123/posts       → 201 Created (create post for user)

// Actions (non-CRUD operations)
POST   /api/users/123/activate    → 200 OK (activate user)
POST   /api/users/123/deactivate  → 200 OK (deactivate user)

Complete API Example

const express = require('express');
const app = express();
app.use(express.json());

let users = [
    { id: 1, name: 'John', email: 'john@example.com' }
];

// GET all users
app.get('/api/users', (req, res) => {
    res.status(200).json({ data: users });
});

// GET single user
app.get('/api/users/:id', (req, res) => {
    const user = users.find(u => u.id === parseInt(req.params.id));
    if (!user) {
        return res.status(404).json({ error: 'User not found' });
    }
    res.status(200).json({ data: user });
});

// POST create user
app.post('/api/users', (req, res) => {
    const { name, email } = req.body;
    
    if (!name || !email) {
        return res.status(400).json({ error: 'Name and email required' });
    }
    
    const newUser = { id: users.length + 1, name, email };
    users.push(newUser);
    res.status(201).json({ data: newUser });
});

// PATCH update user
app.patch('/api/users/:id', (req, res) => {
    const user = users.find(u => u.id === parseInt(req.params.id));
    if (!user) {
        return res.status(404).json({ error: 'User not found' });
    }
    
    Object.assign(user, req.body);
    res.status(200).json({ data: user });
});

// DELETE user
app.delete('/api/users/:id', (req, res) => {
    const index = users.findIndex(u => u.id === parseInt(req.params.id));
    if (index === -1) {
        return res.status(404).json({ error: 'User not found' });
    }
    
    users.splice(index, 1);
    res.status(204).send();
});

app.listen(3000);

// API wrapper with proper error handling
class ApiClient {
    constructor(baseUrl) {
        this.baseUrl = baseUrl;
    }
    
    async request(method, endpoint, data = null) {
        const options = {
            method,
            headers: { 'Content-Type': 'application/json' }
        };
        
        if (data && ['POST', 'PUT', 'PATCH'].includes(method)) {
            options.body = JSON.stringify(data);
        }
        
        const response = await fetch(`${this.baseUrl}${endpoint}`, options);
        
        // Handle different status codes
        if (response.status === 204) return null;
        
        const json = await response.json();
        
        if (!response.ok) {
            throw new Error(json.error || `HTTP ${response.status}`);
        }
        
        return json.data;
    }
    
    getUsers() { return this.request('GET', '/users'); }
    getUser(id) { return this.request('GET', `/users/${id}`); }
    createUser(data) { return this.request('POST', '/users', data); }
    updateUser(id, data) { return this.request('PATCH', `/users/${id}`, data); }
    deleteUser(id) { return this.request('DELETE', `/users/${id}`); }
}

// Usage
const api = new ApiClient('/api');
const users = await api.getUsers();
const newUser = await api.createUser({ name: 'Jane', email: 'jane@example.com' });

async function fetchWithRetry(url, options, retries = 3) {
    for (let i = 0; i < retries; i++) {
        try {
            const response = await fetch(url, options);
            
            // Handle different status code categories
            switch (true) {
                case response.status >= 200 && response.status < 300:
                    return response; // Success!
                
                case response.status === 401:
                    // Refresh token and retry
                    await refreshAuthToken();
                    continue;
                
                case response.status === 429:
                    // Rate limited - wait and retry
                    const retryAfter = response.headers.get('Retry-After') || 5;
                    await delay(retryAfter * 1000);
                    continue;
                
                case response.status >= 500:
                    // Server error - retry with backoff
                    if (i < retries - 1) {
                        await delay(Math.pow(2, i) * 1000);
                        continue;
                    }
                    throw new Error(`Server error: ${response.status}`);
                
                default:
                    // Client errors (4xx) - don't retry
                    const error = await response.json();
                    throw new Error(error.message || `HTTP ${response.status}`);
            }
        } catch (err) {
            if (i === retries - 1) throw err;
        }
    }
}

const delay = ms => new Promise(r => setTimeout(r, ms));

Quick Reference Chart

In practice, these twelve cover most of what a typical API sends back:

Common Mistakes to Avoid

Gotchas I'd Check Before Shipping an API

The tables above are the easy part. These are the things that tend to break once real clients, proxies and load balancers get involved:

• Calling response.json() on a 204. A 204 has no body, so parsing it throws SyntaxError: Unexpected end of JSON input. That's why the client above returns early on 204. The same error shows up when a proxy returns an HTML 502 page and your code assumes JSON, so check the status (or Content-Type) before parsing.
• Redirecting a POST with 301 or 302. Browsers and most HTTP clients turn the follow-up request into a GET and drop the body. If you need the method and body preserved, use 307 or 308.
• Retrying POST blindly. The fetchWithRetry example retries on any 5xx, which is fine for GET but can create duplicates for POST if the server did the work and then timed out. For payments or orders, send an idempotency key header and have the server deduplicate, or don't retry POST at all.
• 401 without WWW-Authenticate. The spec says a 401 response should include that header. Most JSON APIs skip it and nothing breaks, but some clients and tools expect it.

I wouldn't chase "pure REST" too hard, though. If an operation doesn't map to a resource (sending a password reset email, running a report), a POST /api/users/123/reset-password style action endpoint is clearer than inventing a fake resource. And sometimes returning 404 instead of 403 is the right call: if confirming that a private resource exists leaks information, GitHub-style 404s are a reasonable choice. Pick a convention, document it, and make the status code agree with the body.

Mayur Dabhi

Full Stack Developer with 5+ years of experience building web applications with Laravel, React, and Node.js. Passionate about clean code and sharing knowledge.