异常

处理 TypeSafe API 错误、限流、连接失败和超时。

基础异常

typesafe_sdk.TypeSafeError

基类：Exception

SDK 失败的基础异常。

HTTP 错误

typesafe_sdk.TypeSafeAPIError

基类：TypeSafeError

一次不成功的 HTTP 响应，附带其响应体和请求元数据。

status

instance-attribute

status = status

HTTP 响应状态码。

body

instance-attribute

body = body

服务器返回的 JSON 错误体、纯文本响应，或响应体为空时的 None。

headers

instance-attribute

headers = headers

HTTP 响应头。

endpoint

instance-attribute

endpoint = endpoint

请求的方法和 URL；在可用时不含凭据、查询参数或片段。

request_id

property

request_id: str | None

x-typesafe-request-id 响应头，缺失时为 None。

typesafe_sdk.TypeSafeBadRequestError

基类：TypeSafeAPIError

请求无效（400）。

typesafe_sdk.TypeSafeAuthenticationError

基类：TypeSafeAPIError

认证失败（401）。

typesafe_sdk.TypeSafePermissionDeniedError

基类：TypeSafeAPIError

访问被拒绝（403）。

typesafe_sdk.TypeSafeNotFoundError

基类：TypeSafeAPIError

找不到该资源（404）。

typesafe_sdk.TypeSafeUnprocessableEntityError

基类：TypeSafeAPIError

请求未通过服务端校验（422）。

typesafe_sdk.TypeSafeRateLimitError

基类：TypeSafeAPIError

超出了速率限制（429）。

retry_after_ms

instance-attribute

retry_after_ms = parse_retry_after(headers)

服务器要求的等待时间，单位为毫秒；不可用时为 None。

typesafe_sdk.TypeSafeInternalServerError

基类：TypeSafeAPIError

服务器处理请求失败（5xx）。

连接错误

typesafe_sdk.TypeSafeAPIConnectionError

基类：TypeSafeError, ConnectionError

请求失败，且没有 HTTP 响应。

typesafe_sdk.TypeSafeAPITimeoutError

基类：TypeSafeAPIConnectionError, TimeoutError

请求超过了配置的超时时间。

timeout

instance-attribute

timeout = timeout

用于该请求的超时设置，单位为秒，或为一个 httpx2.Timeout。

响应校验

typesafe_sdk.TypeSafeAPIResponseValidationError

基类：TypeSafeAPIError

一次成功的 HTTP 响应，但其响应体缺失了必需的数据，或必需数据在结构上无效。

field_path

instance-attribute

field_path = field_path

指向出错字段的点分路径，例如 answers.tone.confidence。

args

instance-attribute

args = (
    status,
    body,
    headers,
    field_path,
    endpoint,
)