異常

處理 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,
)