HTTP in depth: methods, status codes & headers

The introductory lesson listed the main HTTP methods and a few status codes. To design and debug real APIs you need to know what each method promises, which status code fits which situation, and what the headers are telling you.

Anatomy of a request and response

POST /v1/orders HTTP/1.1
Host: api.example.in
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...
Idempotency-Key: 5f1c2a7e-9b1d-4c1e-a3e2-1f0c6a0d9b11

{"customer_id": 42, "items": [{"sku": "KURTA-M-BLU", "qty": 2}]}

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

{"id": 9812, "status": "pending", "total": "1798.00"}

Safe and idempotent methods

Idempotent means sending the same request twice leaves the server in the same state as sending it once. That is why clients can safely retry a timed-out PUT or DELETE, but retrying a POST /payments could charge a customer twice — unless the API supports an Idempotency-Key header, as most payment gateways do.

Status codes by family

The classic confusion: 401 means "I don't know who you are" (missing or bad credentials), while 403 means "I know who you are, and you are not allowed".

Headers that matter

• Content-Type — the format of the body you are sending (application/json).
• Accept — the format you want back.
• Authorization — credentials, usually Bearer <token>.
• Cache-Control, ETag, If-None-Match — caching; a matching ETag returns 304 with no body.
• Location — URL of a newly created resource.
• Retry-After — how long to wait after a 429 or 503.

Inspecting traffic

curl -i -X GET "https://httpbin.org/get?city=Pune" -H "Accept: application/json"
curl -s -o /dev/null -w "%{http_code}\n" https://httpbin.org/status/404

The -i flag prints response headers; the browser's DevTools Network tab shows the same for web apps.

Common mistakes

• Returning 200 OK with {"error": "not found"} in the body — clients and monitoring tools rely on the status code.
• Using GET for actions that change data; crawlers and prefetchers may trigger them.
• Retrying non-idempotent requests blindly after a timeout.