# HTTP semantics reference

Verified 2026-09 against <https://www.rfc-editor.org/rfc/rfc9110.html> (HTTP semantics),
<https://www.rfc-editor.org/rfc/rfc9457.html> (problem+json),
<https://www.rfc-editor.org/rfc/rfc9745.html> (Deprecation), <https://www.rfc-editor.org/rfc/rfc8594.html> (Sunset)
and <https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/>.

## 1. Status codes, and the ones people get wrong

| Code | Use for | Commonly misused as |
|---|---|---|
| `200` | A successful read or update with a body | A failure with `"success": false` in the body |
| `201` | Created — **with** a `Location` header | Returned without `Location`, so the client cannot find the resource |
| `202` | Accepted for later processing — with a way to track it | A synchronous success the caller then polls for nothing |
| `204` | Success, deliberately no body | Returned with a body, which some clients discard |
| `304` | Not Modified, in response to `If-None-Match`/`If-Modified-Since` | Rarely used at all, so bandwidth is wasted |
| `400` | The request is malformed — unparseable, wrong types | Used for every error including business rules |
| `401` | No or invalid credentials | Used when the caller *is* authenticated but lacks permission |
| `403` | Authenticated, not allowed | Used where `404` belongs, confirming the resource exists |
| `404` | Not found — **and** for resources the caller may not see | Used for a malformed id, which is `400` |
| `409` | State conflict: the resource is not in a state allowing this | Used for validation failures |
| `412` | `If-Match` did not match — someone else changed it | Silently overwriting instead |
| `415` | Unsupported media type | `400` |
| `422` | Syntactically valid, semantically wrong | `400`, losing the distinction clients need |
| `428` | Precondition required — you must send `If-Match` | Accepting the unconditional write |
| `429` | Rate limited — **with** `Retry-After` | Sent with no hint of when to return |
| `500` | An unexpected failure — a bug | Used for downstream failures, which are `502`/`503`/`504` |
| `503` | Temporarily unavailable — with `Retry-After` | `500`, so clients do not know it is retryable |

The `400` / `422` split earns its keep: `400` means "I could not read this", `422` means "I read it and it is wrong". A client can retry neither, but a developer debugging one looks in a very different place.

## 2. Conditional requests end to end

**Caching a read:**

```http
GET /orders/42 HTTP/1.1

HTTP/1.1 200 OK
Cache-Control: private, max-age=60
ETag: "v7-a1b2c3"
```

```http
GET /orders/42 HTTP/1.1
If-None-Match: "v7-a1b2c3"

HTTP/1.1 304 Not Modified
ETag: "v7-a1b2c3"
```

**Guarding a write with the same tag:**

```http
PATCH /orders/42 HTTP/1.1
If-Match: "v7-a1b2c3"
Content-Type: application/merge-patch+json

{ "shippingAddress": { "postcode": "SW1A 1AA" } }
```

`412 Precondition Failed` if the tag no longer matches; `428 Precondition Required` if the header is
missing and your policy requires it. The client's correct response to `412` is to re-read, re-apply
its change and retry — say so in the documentation, because the naive response is to retry without
the header and clobber the other writer.

Generate the `ETag` from something that changes with the row: a version column or a hash of the
representation. A timestamp with one-second resolution allows two writes in the same second to
collide silently.

`Cache-Control` choices: `private` for anything tied to the caller, `no-store` for anything sensitive,
`public` only where the response genuinely does not depend on who asked. Getting this wrong puts one
user's data in a shared proxy.

## 3. Headers and their sources

| Header | Defined by | Notes |
|---|---|---|
| `ETag`, `If-Match`, `If-None-Match`, `Cache-Control`, `Retry-After`, `Location` | RFC 9110 | Core HTTP; every client and proxy understands them |
| `Content-Type: application/problem+json` | RFC 9457 | The error format for this catalog |
| `Deprecation` | RFC 9745 | Structured-field **Date**: `Deprecation: @1735689600` |
| `Sunset` | RFC 8594 | **HTTP-date**: `Sunset: Wed, 31 Dec 2026 23:59:59 GMT`. Must not be earlier than `Deprecation` |
| `Link: …; rel="deprecation"` | RFC 9745 | Points at the migration guide |
| `RateLimit`, `RateLimit-Policy` | IETF draft (draft-11, May 2026) | **Not an RFC.** Widely implemented, still changing |
| `RateLimit-Limit`, `-Remaining`, `-Reset` | De facto | Older convention, still the most widely consumed |
| `Idempotency-Key` | De facto (Stripe-style) | The IETF draft **expired in October 2025** without becoming an RFC |
| `traceparent`, `tracestate` | W3C Trace Context | Accept and propagate them (`service-operability`) |

The point of this table is to stop two failure modes: citing an RFC number that does not exist for a
header, and implementing a draft as though it were settled. For `Idempotency-Key` and the rate-limit
fields, document your own semantics — that is what clients will code against.

## 4. Deprecating a field or an endpoint

```http
HTTP/1.1 200 OK
Deprecation: @1735689600
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: <https://api.example.com/docs/v2-migration>; rel="deprecation"; type="text/html"
```

The sequence that actually works:

1. Add the replacement **alongside** the old field. Both are populated.
2. Mark the old one `deprecated: true` in the OpenAPI document and start sending the headers.
3. **Measure** usage per client. This is the step that gets skipped, and it is the only one that
   tells you whether removal is safe.
4. Contact the remaining consumers directly. A header is not a conversation.
5. Remove after the sunset date, in a major version.

A field-level deprecation inside a version is legitimate — `deprecated: true` on a schema property is
part of OpenAPI — and is much cheaper than a whole new major version for one rename.

## 5. Batch and bulk

```http
POST /orders:batch HTTP/1.1
Content-Type: application/json

{ "items": [ { "sku": "A1", "qty": 2 }, { "sku": "B2", "qty": 0 } ] }
```

```http
HTTP/1.1 200 OK
Content-Type: application/json

{ "results": [
    { "index": 0, "status": 201, "id": "01JD…" },
    { "index": 1, "status": 422,
      "error": { "type": "https://api.example.com/problems/validation",
                 "title": "qty must be >= 1", "status": 422 } } ] }
```

Rules that make a batch endpoint usable:

- **Per-item status.** One bad row must not fail the batch, and the caller must be able to tell which.
- **The envelope status is about the envelope**: `200` means "I processed your batch", not "everything
  succeeded". Document this loudly — it surprises people.
- **Cap the item count** and return `413` or `422` above it. An uncapped batch is an unplanned
  long-running request.
- **Partial success is the default**; offer all-or-nothing only if you can really do it in one
  transaction, and say which you are.
- **Idempotency applies to the batch as a whole**: one `Idempotency-Key` for the request, so a retry
  does not half-repeat it.

## 6. Webhook delivery

Sending:

```http
POST /hooks/orders HTTP/1.1
Webhook-Id: 01JD8ZQ3H7
Webhook-Timestamp: 1767225600
Webhook-Signature: v1,5d41402abc4b2a76b9719d911017c592
Content-Type: application/json

{ "id": "01JD8ZQ3H7", "type": "order.placed", "occurredAt": "2026-01-01T00:00:00Z",
  "resource": "https://api.example.com/orders/42" }
```

- **Sign** over the timestamp and the raw body with HMAC-SHA256 and a per-subscriber secret. Receivers
  verify in **constant time** and reject a timestamp older than a few minutes, which is what stops a
  captured request being replayed forever.
- **Support two secrets at once** so a subscriber can rotate without dropping deliveries.
- **Delivery is at least once.** The `id` is what lets the receiver deduplicate — the receiving side
  of this is `messaging-patterns` §3.
- **Retry** with capped jittered backoff over hours, then dead-letter and expose a replay endpoint.
  Disable a subscription that has failed for days, and tell its owner.
- **Thin events** — id, type, and a URL to fetch the resource — avoid leaking data to a stale endpoint
  and avoid versioning a full payload. The cost is a callback, which is usually worth it.
