Generate API reference docs from code

Write API reference documentation from this code.

Per endpoint, in this order:
1. What it does, in one sentence, from the caller's point of view.
2. Request — path, method, auth, parameters. Mark required versus optional, with types and constraints.
3. A working example request.
4. Success response, with a real example body and what each field means.
5. **Error responses — every status the code can return, what triggers it, and what the caller should do.** *This is the section that is always missing and the one callers actually need.*
6. Constraints not visible in the signature: rate limits, size limits, idempotency, ordering guarantees, pagination behavior.
7. What changes state and what does not, and whether retrying is safe.

Rules:
- *Document only what the code shows.* Where behavior is unclear, write "not determinable from the code" and say what to check — do not write the plausible answer.
- Field descriptions say what the value means, not its type. The type is already in the table.
- Flag any parameter whose name does not match what it does. That is a documentation finding and a design finding.
- Note where the code and any existing comments disagree.