Write examples that aren't toys

Docs whose only example is foo and bar and helps nobody.

Write documentation examples for the feature below.

Rules:
- Use realistic domain data. No `foo`, `bar`, `test123`, or `MyClass`. Pick a plausible domain and stay in it across every example.
- Every example must be complete enough to run: imports, setup, and the output shown underneath as a comment or block.
- Give three, in escalating order: the minimal case, the one most people actually need, and one awkward real case such as pagination, an error, or a partial failure.
- Show error handling in at least one, not as a `try` with an empty body.
- Annotate only the lines that are not obvious. Do not comment every line.

After the examples, list the mistakes users will most likely make when adapting these, and add one line to the relevant example guarding against each.

Feature and its API:

Reference and API docs. The lookup layer: function docs, config options, error codes and examples worth copying.