[kelsayed17]

What changes

Four bugs that an adversarial review of the public API turned up, each reproduced by a test that failed before the fix.

• post(json=..., data=...) raises ValueError. httpx2 sent the form alone and silently dropped the JSON; check_one_body promised to refuse exactly that and did not check this pair.
• A call's retry=True undoes its view's retry=False. A verb's retry= defaulted to True, which doubled as "inherit", so a call could not override a view's retry=False, contrary to "a call's own options win over the view's". The default is now None (the view's); True skips the view, leaving the route's policy or the client's (a route's NO_RETRY still holds, and a test pins that).
• A value of the wrong kind is refused where it is written, with a TypeError naming the option and what it takes: rate=10, TransportPolicy(retry=None) (points at NO_RETRY), TransportPolicy(breaker=3), and timeout=5.0 on HttpOptions, with_options or a call (refused before anything is sent). Each used to pass construction and fail at the first request with an AttributeError.
• paginate fetches pages through AsyncBaseClient's own get/post, so an SDK subclass whose endpoint method is named get or post can still paginate; before, every walk raised a TypeError from the subclass's method.

Also: BudgetBacklogError's docstring no longer claims it is public (callers only ever see it as ClientTimeoutError).

For reviewers: the retry default change is visible in the public signatures (verbs, stream, paginate), so the API-surface snapshot changed; the diff is only retry: 'bool | RetryPolicy' = True → retry: 'bool | RetryPolicy | None' = None. It is listed under Changed in the changelog. Not changed on purpose: using a closed client still raises RuntimeError, which an existing test pins. Other late-failing wrong-kind values (e.g. paginate(limit=100)) are left for a follow-up.

Checklist

• uv run ruff check, uv run ruff format --check and uv run ty check pass, with no suppression comments
• uv run python -m pytest --cov passes at 100% line and branch coverage
• Docs (README / docs/) and docstrings describe the new behaviour
• CHANGELOG.md has an entry under "Unreleased"
• A change to the public API is reflected in the API-surface snapshot (--snapshot-update, diff reviewed)

🤖 Generated with Claude Code

[codspeed]

Merging this PR will not alter performance

✅ 44 untouched benchmarks

---

_{Comparing claude/public-api-elegance-eval-47a0c1 (18d9576) with main (713b4e5)}