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:
GET /orders/42 HTTP/1.1
HTTP/1.1 200 OK
Cache-Control: private, max-age=60
ETag: "v7-a1b2c3"
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:
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/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:
- Add the replacement alongside the old field. Both are populated.
- Mark the old one
deprecated: truein the OpenAPI document and start sending the headers. - Measure usage per client. This is the step that gets skipped, and it is the only one that tells you whether removal is safe.
- Contact the remaining consumers directly. A header is not a conversation.
- 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
POST /orders:batch HTTP/1.1
Content-Type: application/json
{ "items": [ { "sku": "A1", "qty": 2 }, { "sku": "B2", "qty": 0 } ] }
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:
200means "I processed your batch", not "everything succeeded". Document this loudly — it surprises people. - Cap the item count and return
413or422above 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-Keyfor the request, so a retry does not half-repeat it.
6. Webhook delivery
Sending:
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
idis what lets the receiver deduplicate — the receiving side of this ismessaging-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.