Conventions split into four pages

Date: 2026-05-06

The Conventions section used to be a single placeholder page. Each of its four bullet points has graduated into a discrete page so it can stand on its own and be linked to from recipes:

• Pagination — page + pageSize query parameters, the PaginatedResult<T> envelope, walking every page, and explicit non-goals (no cursors, no Link header, no return-everything escape hatch).
• Errors — RFC 7807 ProblemDetails shape, the four canonical status mappings, the traceId extension, and the typed Result<T> failure model with a link to the error codes catalog.
• Idempotency — the IdempotencyKey body field on POST /orders, the retry contract, key lifetime, and what isn’t covered (no header model, no body-content matching, no refund / void idempotency).
• Rate limits — the active policies (contact-form and the two MFA policies), the 429 shape, and recommended exponential-backoff retry.

Why split

The single placeholder had two problems:

1. Discoverability. A recipe that needs to talk about idempotency couldn’t link to a specific anchor without forcing readers to scroll past pagination and errors first.
2. Authoring depth. Each topic warranted three to five paragraphs plus code samples. Cramming them into one page either bloated it beyond a comfortable scroll or compressed each topic to the point of uselessness.

Migration

Existing bookmarks to /conventions/ continue to resolve. The page now serves as a landing index that points at the four sub-pages.