[TexasCoding]

Closes #246

Part of #273 (post-v2.4 audit), Wave 0 docs patch.

[claude]

Code Review — PR #277: docs(migration): v2.3→v2.4 section

Good fix for #246. The section covers all five v2.4 features and the examples read clearly. I verified each claim against the implementation. One critical bug in the code examples, plus a couple of minor notes.

---

🔴 Critical: get_by_client_order_id does not exist

The exception-handling examples call a method that is not implemented:

# KalshiConflictError handler
existing = client.orders.get_by_client_order_id(req.client_order_id)

# KalshiTimeoutError handler
existing = client.orders.get_by_client_order_id(req.client_order_id)

OrdersResource has no such method. The only retrieval methods are get(order_id: str) (looks up by server-assigned order_id) and list(...) (which does not accept client_order_id as a filter). Any user who follows this guide will get AttributeError.

The reconciliation pattern is the most safety-critical part of this section — it's the exact flow users need to avoid duplicate orders after a timeout. Shipping it with a broken API call is worse than no example at all.

Suggested fix: Replace both occurrences with the correct pattern. Depending on whether a get_by_client_order_id endpoint is planned for v2.5, either:

• Use a list call that filters by ticker + status as a stand-in, with a TODO note; or
• Show client.orders.get(order_id) with a note that the caller must have recorded the order_id from a prior call; or
• Add a get_by_client_order_id resource method before merging this guide.

---

🟡 Minor: Docstring version labels conflict with migration guide

orders.py lines 476 and 514 say:

BREAKING in v3.0.0: previously returned ``list[Order]`` …
BREAKING in v3.0.0: previously returned ``None`` …

This PR and the CHANGELOG both place these breaking changes at v2.4, not v3.0. Not introduced here, but it's confusing for any developer reading the docstring after following the migration guide. Worth a follow-up fix to align the labels.

---

🟢 Verified correct

Claim	Status
KalshiConflictError / KalshiTimeoutError / KalshiPoolExhaustedError exist and are exported	✅ errors.py:65,69,77; __init__.py:11,15,20
422 now routes to KalshiValidationError	✅ _base_client.py:72
batch_create → BatchCreateOrdersResponse	✅ resources/orders.py:487
batch_cancel → BatchCancelOrdersResponse	✅ resources/orders.py:529
from_pem / from_key_path / from_env / try_from_env accept password=	✅ auth.py:84,109,151,192
KALSHI_PRIVATE_KEY_PASSPHRASE read by from_env and try_from_env	✅ auth.py:170,211
KalshiConfig(http2=True) with fail-fast on missing h2	✅ config.py:68,91-97
pip install 'kalshi-sdk[http2]' — package name and extra are correct	✅ pyproject.toml:2,29
extra_headers on KalshiConfig and both transports	✅ _base_client.py:161,183,205,344,366,386

---

Verdict: The get_by_client_order_id examples must be fixed before merging — they will silently teach users a broken reconciliation flow. Everything else checks out.