docs(index): extract pagination recipe and restructure Errors blurb

Quick-Start was carrying a ~37-line `send_with_response` walkthrough that
is really a use-case recipe — moves to `docs/recipes/link-header-pagination.md`
under the existing Recipes nav group, framed around RFC 5988 Link pagination
with `send_with_response` as the mechanism. Quick-Start keeps a one-sentence
pointer next to the typed-decoding example.

The landing-page `## Errors` section was a single dense paragraph cataloging
six exception classes across three categories — replaced with a four-bullet
scan list (status / transport / resilience / decode) and a link to the full
`errors.md` reference.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: lesnik512

docs/index.md

@@ -62,6 +62,8 @@ async def main() -> None:
         print(user.name)
 ```
 
+Need the raw response **and** a decoded body from the same call (e.g., for header-based pagination)? See [Link header pagination](recipes/link-header-pagination.md) — it uses `send_with_response`.
+
 ### With resilience middleware
 
 Compose resilience middleware at construction; `AsyncBulkhead` goes outside `AsyncRetry` so one slot covers all retry attempts.
@@ -81,44 +83,6 @@ async def main() -> None:
         user = await client.get("/users/1", response_model=User)
 ```
 
-### Response metadata + typed body
-
-When you need both the raw `httpx2.Response` (for headers, status, or the
-request URL) **and** a typed body, use `send_with_response`. It returns
-both atomically and routes the decode through the configured
-`ResponseDecoder`, so decoder failures surface as `DecodeError` — caught
-by `except httpware.ClientError` like every other failure mode.
-
-Canonical use case: RFC 5988 Link header pagination.
-
-Assume `process` and `next_link` are caller-defined — pick a Link header parser that fits.
-
-```python
-from httpware import AsyncClient
-from pydantic import BaseModel
-
-
-class Tag(BaseModel):
-    name: str
-
-
-async def main() -> None:
-    async with AsyncClient(base_url="https://gitlab.example/api/v4") as client:
-        url = "/projects/1/repository/tags"
-        params: dict[str, str] | None = {"per_page": "100", "page": "1"}
-        while url:
-            request = client.build_request("GET", url, params=params)
-            response, tags = await client.send_with_response(request, response_model=list[Tag])
-            for tag in tags:
-                process(tag)
-            url = next_link(response.headers.get("link"))   # caller's parser
-            params = None                                    # next link carries query
-```
-
-For body-only with a high-level verb, prefer `client.get(..., response_model=...)`.
-For body-only with a custom `Request`, prefer `client.send(request, response_model=...)`.
-`send_with_response` is not for streaming responses — use `stream()`.
-
 ### Streaming responses
 
 For large responses or server-sent events, stream the body chunk-by-chunk. `stream()` is an async context manager:
@@ -140,7 +104,14 @@ It does NOT pass through the middleware chain: `AsyncRetry`, `AsyncBulkhead`, an
 
 ## Errors
 
-All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `ServiceUnavailableError`, `RateLimitedError`, etc. — all subclasses of `httpware.StatusError`. Transport-layer transient failures raise `NetworkError`; the resilience middleware raise `RetryBudgetExhaustedError` and `BulkheadFullError`. Everything inherits `httpware.ClientError`.
+All errors inherit `httpware.ClientError`. The categories:
+
+- **Status errors** (4xx/5xx responses) — raised automatically, no `raise_for_status()` needed: `NotFoundError`, `RateLimitedError`, `ServiceUnavailableError`, and the rest. All subclass `StatusError`.
+- **Transport errors** — connection / network / protocol failures before a response arrived. `NetworkError` (transient) subclasses `TransportError`.
+- **Resilience refusals** — `RetryBudgetExhaustedError` and `BulkheadFullError`, raised by the resilience middleware.
+- **Decode errors** — `DecodeError`, raised when `response_model=` decoding fails (HTTP call itself succeeded).
+
+See the [Errors reference](errors.md) for the full tree and catching strategies.
 
 ## Observability
 

docs/recipes/link-header-pagination.md

@@ -0,0 +1,39 @@
+# Link header pagination
+
+GitLab, GitHub, and other APIs paginate via the [RFC 5988](https://datatracker.ietf.org/doc/html/rfc5988) `Link` response header: each page response carries a `Link: <…>; rel="next"` header pointing to the next page. To walk all pages you need both the decoded body **and** the response headers from the same call — `client.get(..., response_model=...)` returns only the body.
+
+`send_with_response` returns both atomically. It routes the decoded body through the configured `ResponseDecoder`, so decoder failures surface as `DecodeError` — caught by `except httpware.ClientError` like every other failure mode.
+
+## The pagination loop
+
+```python
+from httpware import AsyncClient
+from pydantic import BaseModel
+
+
+class Tag(BaseModel):
+    name: str
+
+
+async def main() -> None:
+    async with AsyncClient(base_url="https://gitlab.example/api/v4") as client:
+        url = "/projects/1/repository/tags"
+        params: dict[str, str] | None = {"per_page": "100", "page": "1"}
+        while url:
+            request = client.build_request("GET", url, params=params)
+            response, tags = await client.send_with_response(request, response_model=list[Tag])
+            for tag in tags:
+                process(tag)
+            url = next_link(response.headers.get("link"))   # caller's parser
+            params = None                                    # next link carries query
+```
+
+`process` and `next_link` are caller-defined. Pick a Link-header parser that fits your project — there are several on PyPI, and the format is small enough to hand-roll.
+
+## When to use which API
+
+- **Body only, high-level verb:** `client.get(..., response_model=...)`
+- **Body only, custom `Request`:** `client.send(request, response_model=...)`
+- **Body + response metadata:** `client.send_with_response(request, response_model=...)`
+
+`send_with_response` is not for streaming responses — use [`stream()`](../index.md#streaming-responses) for those.

mkdocs.yml

@@ -13,6 +13,7 @@ nav:
   - Recipes:
       - modern-di: recipes/modern-di.md
       - Phase decorator patterns: recipes/phase-decorator-patterns.md
+      - Link header pagination: recipes/link-header-pagination.md
   - Development:
       - Contributing: dev/contributing.md