HTTP semantics: methods, status, headers and caching
Before versions and transports, HTTP is a contract: what a method promises, what a status means, and which headers let caches and retries work safely.
HTTP separates semantics, what a request means, from wire format, how it is encoded. A GET /users/7 means the same thing in HTTP/1.1, HTTP/2 and HTTP/3. Only the bytes differ. This lesson is about the meaning; the next lessons are about the bytes.
An HTTP/1.1 exchange, annotated
POST /v1/messages HTTP/1.1 Request line: method, path and protocol version. POST is neither safe nor idempotent, so it must not be retried blindly.
Methods carry promises
| Method | Safe | Idempotent | Meaning |
|---|---|---|---|
| GET | Yes | Yes | Read a resource. Must not change state. |
| HEAD | Yes | Yes | Like GET, headers only. |
| PUT | No | Yes | Replace the resource with this body. Repeating it changes nothing further. |
| DELETE | No | Yes | Remove it. Deleting twice leaves it deleted. |
| POST | No | No | Process this. Repeating may create two orders or two charges. |
| PATCH | No | Not guaranteed | Apply a partial change. |
Safe means no state change. Idempotent means doing it twice has the same effect as once. These properties decide what can be retried automatically: a client, proxy or browser may resend an idempotent request after a dropped connection, but must not blindly resend a POST. That is why payment APIs accept an Idempotency-Key header: it makes a POST safe to retry.
Status codes by family
| Range | Meaning | Ones to know |
|---|---|---|
| 1xx | Informational, more is coming | 101 Switching Protocols (WebSocket), 103 Early Hints |
| 2xx | Success | 200 OK, 201 Created, 204 No Content |
| 3xx | Go elsewhere or use your cache | 301/308 permanent, 302/307 temporary, 304 Not Modified |
| 4xx | The request is wrong; do not retry unchanged | 400, 401, 403, 404, 409 Conflict, 429 Too Many Requests |
| 5xx | The server failed; retry may help | 500, 502 Bad Gateway, 503 Unavailable, 504 Gateway Timeout |
Caching headers
Cache-Control tells caches what they may do: max-age=3600 (fresh for an hour), no-store (never keep), private (only the user's own browser), immutable (never revalidate). Validators let a cache ask “has it changed?” cheaply: the server sends an ETag, the client later sends If-None-Match, and an unchanged resource returns 304 Not Modified with no body.
- First response
200 OK,ETag: "v42", 480 KB body- Later request
If-None-Match: "v42"- Resource unchanged
304 Not Modified, empty body, a few hundred bytes of headers
Same round trip, 99.9% fewer bytes. Tool results fetched repeatedly by an agent benefit the same way.
Keep-alive
HTTP/1.0 opened a new TCP connection per request. HTTP/1.1 made connections persistent by default: after a response, the connection stays open for the next request. That avoids repeating the TCP and TLS handshakes and slow start. But one HTTP/1.1 connection carries one request at a time. Browsers open up to six connections per origin to work around this, and that limit returns when we discuss SSE.
Go deeperChunked transfer: streaming in HTTP/1.1
A response usually announces its size with Content-Length. A streaming response does not know its size in advance, so HTTP/1.1 uses Transfer-Encoding: chunked: each chunk is its length in hexadecimal, a line break, the bytes, and another line break. A zero-length chunk ends the body.
HTTP/1.1 200 OK
Content-Type: text/event-stream
Transfer-Encoding: chunked
19
data: {"delta":"Hello"}\n\n
1a
data: {"delta":" world"}\n\n
0
Chunk boundaries are a transport detail. A proxy may merge or split them, so a client must never treat one chunk as one event. HTTP/2 and HTTP/3 drop chunked encoding entirely; their DATA frames do the same job.
Where you will meet it
Model SDKs retry 408, 429 and 5xx responses with backoff, and only when the request is safe to repeat or carries an idempotency key.
Static assets with content hashes in their names are served with Cache-Control: max-age=31536000, immutable, so browsers never even ask again.
A web-fetch tool that sends If-None-Match for pages it has already read saves both bandwidth and the tokens of re-reading unchanged content.
Words to know
- Idempotent
- Repeating the operation has the same effect as doing it once.
- ETag
- An opaque version identifier a server attaches to a response.
- Persistent connection
- A connection reused for many requests, also called keep-alive.
- Chunked encoding
- HTTP/1.1's way to stream a body of unknown length.
Check yourself
Answer out loud before you open each one.
What is the difference between safe and idempotent?
Safe means no state change at all. Idempotent means repeating the request has the same effect as doing it once.
Why do payment APIs accept an Idempotency-Key header?
It lets a client safely retry a POST: the server returns the stored result for a repeated key instead of charging twice.
What does a 304 response save?
The body. The client already has the current version, confirmed by its validator.
Try it
Run curl -sI https://example.com and read the caching headers. Then repeat with -H 'If-None-Match: <the etag>' and check for a 304.