structured_targets.get() docs claim 404→None mapping that does not exist #320

Problem

docs/resources/structured-targets.md tells readers that get() may return None for unknown IDs because "the underlying endpoint returns a 404 that's mapped to None rather than KalshiNotFoundError." That is not what the code does. StructuredTargetsResource.get calls plain _get(...) and unwraps GetStructuredTargetResponse.structured_target. There is no try/except in the resource and no 404→None carve-out in the transport — _map_error uniformly returns KalshiNotFoundError for 404. The StructuredTarget | None return annotation reflects the spec-optional envelope field (server may return 200 with {"structured_target": null}), not a 404-coalesce.

Readers following the documented if t is None: branch will never see it fire on missing IDs; instead KalshiNotFoundError propagates unhandled.

Evidence

• docs/resources/structured-targets.md:47-48:

`get()` may return `None` for unknown IDs (the underlying endpoint returns a
404 that's mapped to `None` rather than `KalshiNotFoundError`).

• kalshi/resources/structured_targets.py:85-92:

def get(
    self, structured_target_id: str, *, extra_headers: dict[str, str] | None = None
) -> StructuredTarget | None:
    data = self._get(
        f"/structured_targets/{_seg(structured_target_id, name='structured_target_id')}",
        extra_headers=extra_headers,
    )
    return GetStructuredTargetResponse.model_validate(data).structured_target

• kalshi/_base_client.py:88-89:

if status == 404:
    return KalshiNotFoundError(message=message, status_code=status)

Suggested fix

Rewrite the doc paragraph to match observed behavior, e.g.:

A 404 from the server raises KalshiNotFoundError. get() returns None only if the server responds 200 with {"structured_target": null} — a server-side soft-not-found that the spec permits but is rare in practice.

Also update the snippet immediately above so it shows the realistic pattern (try / except KalshiNotFoundError) alongside the rare is None branch.

Source

Round-3 independent audit (reviewer: resources_api).