Expose typed chat request validation errors separately from execution failures #562

Problem

PageIndex 0.2.22 raises PageIndexAPIError for both locally invalid chat requests and execution failures. SDK callers cannot reliably distinguish these cases programmatically.

For example, local_chat._refuse_skeleton({"tools": []}) rejects an SDK-managed field with PageIndexAPIError(status_code=None). Invalid native messages and invalid max_turns also use this exception. Provider failures without a status, agent failures, and an empty Messages result can use the same class and missing status.

The exception class and an absent status code are insufficient to identify validation failures. Callers should be able to distinguish them without matching exception text or duplicating the SDK's validation rules.

Requested SDK contract

• Expose a stable, machine-readable distinction for request validation failures, such as a public validation exception subclass or error category.
• Apply it consistently across Chat Completions, Responses, and Messages, including failures reached during iterator consumption.
• Keep provider/tool failures distinct and preserve available upstream status/cause information.
• Document which error details callers may safely expose to their users.

Acceptance

Behavior tests distinguish SDK-managed tools overrides, malformed native messages, and invalid turn limits from provider transport errors, tool failures, and empty model responses without inspecting exception strings.