HTTP in Depth

After this lesson, you will be able to: Use HTTP status codes correctly, set the right headers (Content-Type, Authorization, Accept, CORS, Cache-Control).

HTTP details, status codes + headers, are where APIs feel professional vs amateur. Get these right and clients + tools just work.

Prerequisites:What an API is and what REST means

Status codes — the ones you'll actually use

2xx Success: 200 OK (read), 201 Created (POST that made a new resource), 204 No Content (DELETE / successful no-body response). 3xx Redirect: 301 Moved Permanently, 302 Found (temporary), 304 Not Modified (cached). 4xx Client error: 400 Bad Request, 401 Unauthorized (no/bad credentials), 403 Forbidden (logged in but not allowed), 404 Not Found, 409 Conflict (e.g., email already taken), 422 Unprocessable Entity (validation failure), 429 Too Many Requests. 5xx Server error: 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable.

Standard headers

What clients send + what servers send back.

tsx

// Client → Server
Content-Type: application/json          // what I'm sending
Accept: application/json                // what I can accept back
Authorization: Bearer eyJhbGc...        // who I am
User-Agent: MyApp/1.2                   // identify your client

// Server → Client
Content-Type: application/json; charset=utf-8
Cache-Control: max-age=300              // cache for 5 minutes
ETag: "abc123"                          // fingerprint of the response body
Location: /users/42                     // for 201 Created, where the new resource lives
X-RateLimit-Limit: 60                   // custom rate-limit headers
X-RateLimit-Remaining: 42

CORS — Cross-Origin Resource Sharing

Why browsers block your fetch calls.

tsx

// If your frontend at https://app.example.com fetches from https://api.example.com,
// the browser checks if api.example.com explicitly allows it via CORS headers.

// Server response must include:
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization

// For preflight (OPTIONS) requests on non-simple requests:
Access-Control-Max-Age: 86400

// Wildcard (Access-Control-Allow-Origin: *) is fine for PUBLIC APIs.
// For authenticated APIs (cookies / Authorization header), you MUST set
// a specific origin + Access-Control-Allow-Credentials: true.

Cache-Control basics

Tell intermediaries what to cache.

tsx

// No caching (sensitive data)
Cache-Control: no-store

// Private cache only (the browser, not CDNs)
Cache-Control: private, max-age=60

// Public cache, 5 min
Cache-Control: public, max-age=300

// Stale-while-revalidate (serve cached up to 1h while revalidating)
Cache-Control: public, max-age=60, stale-while-revalidate=3600

// Conditional requests (304 Not Modified)
ETag: "v3"
// Client sends next time:
If-None-Match: "v3"
// Server returns 304 with empty body if unchanged

Common mistakes

Returning 200 with `{error: '...'}` instead of the correct 4xx code. Missing Content-Type → client guesses + sometimes wrong. CORS misconfigured for credentials (wildcard origin + credentials = browser blocks). Cache-Control: no-cache (means 'revalidate', NOT 'don't cache', use no-store).

←What an API is and What REST Means

Back to REST APIs

Designing a REST API→