Request & response anatomy

Strip away the client library and an HTTP/1.1 request is a few lines of text. This is exactly what curl sent to a local API (captured with curl -v, which the next unit covers):

POST /orders HTTP/1.1
Host: localhost:4123
User-Agent: curl/8.7.1
Content-Type: application/json
Accept: application/json
Content-Length: 23

{"sku":"TEA-1","qty":2}

Four parts, always in this order (RFC 9112, section 2.1):

1. The request line — method SP target SP version. POST is what to do, /orders is what to do it to, HTTP/1.1 is the protocol.
2. Header fields — one Name: value per line. Metadata about the request: who the host is, what the body is, what the client wants back.
3. An empty line — the only thing that says "headers are over".
4. The body (optional) — exactly Content-Length bytes of data. A GET usually has none.

The response has the same shape; only the first line differs:

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 32
Location: /orders/43
Date: Sat, 17 Oct 2026 06:45:44 GMT

{"id":43,"sku":"TEA-1","qty":2}

The status line carries the version, a three-digit status code and a reason phrase. Software reads the code; the phrase is for humans and may be anything. 201 Created plus a Location header is how a server says "I made a new thing, and here's its URL" (RFC 9110, section 9.3.3).

Three habits this gives you:

• When an API "ignores your body", look for the missing or wrong Content-Type before you look at the server code.
• Header names are case-insensitive (content-type and Content-Type are the same field); header values often aren't.
• Debugging HTTP means reading these lines. Everything else — fetch, axios, a NestJS controller — builds or parses them for you.

Two properties of a method decide what browsers, proxies, prefetchers and retry loops are allowed to do with your request. RFC 9110 (section 9.2) defines both.

Safe — the client asks for no state change. A crawler, a link prefetcher or a cache may send it without fear. Idempotent — sending it N times has the same intended effect on the server as sending it once.

Every safe method is idempotent; not every idempotent method is safe.

Idempotent is about the effect, not the response

DELETE /orders/7   ->  204 No Content
DELETE /orders/7   ->  404 Not Found

Different responses, same effect: order 7 doesn't exist. RFC 9110 says so explicitly — the repeat has "the same intended effect, even if the original request succeeded, though the response might differ". Logging, metrics and audit rows don't count against idempotency either; only what the client asked for does.

Why it matters: retries after a lost response

The dangerous moment is a request sent and no response received — a timeout, a dropped connection. Did the server do it? The client can't know. RFC 9110 draws the line:

• An idempotent request "can be repeated automatically" after a communication failure: if the first one landed, the second changes nothing.
• A client SHOULD NOT automatically retry a non-idempotent request unless it has some way to know it's safe. A proxy MUST NOT.

So a retry helper that wraps every call in "try three times" is fine for GET and PUT and a double-charge bug for POST /payments.

Safe is a promise you make as a server

GET /emails/42?action=archive

If that archives the email, every link checker, preview bot and prefetcher that follows the URL archives it too. RFC 9110 puts this on the resource owner: an unsafe action reached through a safe method must be disabled. Use POST /emails/42/archive (or PATCH the email's state) instead.

POST /payments times out. Three different things may have happened, and the client can't tell them apart:

1. The request never reached the server.
2. The server charged the card, and the response was lost on the way back.
3. The server is still working on it.

A 502 or 504 from a gateway is the same uncertainty in status-code form: the proxy gave up on the upstream, but the upstream may have finished the work. Retrying blindly turns outcome 2 into a double charge; not retrying turns outcome 1 into a lost order.

One key per operation, reused on every attempt

The fix is to make the POST recognisable. The client generates a unique key for the operation — the user's one click on "Pay" — and sends it on the first attempt and on every retry of that operation:

async function createPayment(input: PaymentInput, send: typeof fetch) {
  const key = crypto.randomUUID();                // ONCE, outside the loop
  for (let attempt = 1; ; attempt++) {
    try {
      const res = await send("/payments", {
        method: "POST",
        headers: { "Content-Type": "application/json", "Idempotency-Key": key },
        body: JSON.stringify(input),
      });
      if (!RETRYABLE.has(res.status) || attempt === MAX_ATTEMPTS) return res;
      await sleep(delayFor(res, attempt));        // honour Retry-After if present
    } catch (err) {
      if (attempt === MAX_ATTEMPTS) throw err;    // no response: the same key makes a resend safe
      await sleep(delayFor(null, attempt));
    }
  }
}

On the server, the key is a lookup before any work: first time seen → do the work and store the response under the key; seen and finished → return the stored response without doing anything; seen and still running → refuse with 409 Conflict; same key with a different body → 422, because the client is misusing the key. Keys expire after a documented window.

Generate the key inside the loop and every attempt looks like a brand-new payment — the header is present, and it protects nothing.

What's worth retrying at all

Retry-After is either a number of seconds or an HTTP date (RFC 9110, section 10.2.3). When the server sends one, it knows more than your exponential backoff does.