HTTP in depth: methods, status codes and headers

HTTP (HyperText Transfer Protocol) is the set of rules a client and a server follow to talk. It is plain text, it is request and response, and it is the base of every web API you will build.

A client sends a request. The server sends back one response. Each message is small and independent: the server does not remember the previous one (that is why we call HTTP stateless).

POST /orders HTTP/1.1
Host: api.brewandbean.example
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJhbGciOi...

{"customer_name": "Asha", "phone": "9876543210", "items": [{"item_id": "espresso", "qty": 2}]}

Line 1 is the request line: method, path, version. Then headers, a blank line, then the optional body.

HTTP/1.1 201 Created
Content-Type: application/json
Location: /orders/42

{"id": 42, "status": "received", "total": 240}

The status line has the code and its reason phrase. Then headers, a blank line and the body.

The method says what you want to do with the resource. Two properties matter:

- Safe: it does not change anything on the server (it only reads). - Idempotent: doing it once or ten times leaves the server in the same state. This matters when a network drops and the client retries.

Why idempotency matters: if POST /orders times out and the app retries, the customer may get two coffees. PUT /menu/espresso with the same body twice is harmless. For payments and orders, APIs often accept an idempotency key header so a retried request is recognised as the same one.

The status code is a three-digit number telling the client what happened. The first digit is the family. Always return an accurate code: clients and tools rely on it.

Headers are Name: value pairs that carry information about the message, not the data itself. Names are case-insensitive. These are the ones you will use constantly.

Content-Type is the one beginners forget. If you send JSON but leave out Content-Type: application/json, many frameworks will not parse the body and you will see empty data or a 415 or 422 error.

curl is a command-line HTTP client, included with Windows 10 and 11, macOS and Linux. We will call a free public test API, JSONPlaceholder, which accepts requests and returns fake data. On Windows PowerShell, type curl.exe (plain curl is an alias for something else); in Git Bash, curl works.

curl -i https://jsonplaceholder.typicode.com/posts/1

-i prints the response headers as well as the body.

curl -i -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{"title": "coffee", "body": "cold brew", "userId": 1}'

Expect 201 Created and a JSON body with a new id. In Windows PowerShell, use curl.exe and write it on one line with the JSON in single quotes escaped as "{\"title\": \"coffee\"}", or use Git Bash.

curl -i https://jsonplaceholder.typicode.com/posts/99999

Returns 404 Not Found with an empty JSON object.

You can watch real HTTP in the browser: open DevTools (F12), choose the Network tab, reload a page and click any request to see its method, status, headers and body.

Common questions: the difference between PUT and PATCH (replace versus partial update); what idempotent means and which methods have it; 401 versus 403; when to return 201 versus 200; what CORS is and why the browser blocks a request; what happens on GET versus POST regarding caching and bodies. Give a short definition and one example each.

I called [METHOD] [URL] and received status [CODE] with this response body:

---
[paste body and relevant headers]
---

Explain in plain English what the status code means, the most likely causes in my situation ([framework, e.g. FastAPI]) and what I should check first. Do not guess; list causes in order of likelihood.

What to expect: A good answer separates client mistakes (4xx) from server bugs (5xx) and suggests concrete checks such as the Content-Type header, the URL spelling or the server logs.