# 錯誤處理與重試

[HTML](https://pdfcraft.ai/zh-Hant/docs/api/error-handling/) · [Site index](https://pdfcraft.ai/llms.txt)

在轉換任務失敗或耗時超出預期時，建立可預測的整合機制。


將轉換結果視為具狀態的任務，而非同步的檔案下載。當來源檔案過大、無法取得或格式錯誤時，這能讓你的產品保持穩定可靠。

## 安全地重試

僅重試可安全重複的請求。結果請求可使用指數退避進行重試。對於提交請求，請先保存成功回應所回傳的任務 ID，再嘗試再次提交。

## 處理終止性失敗

當任務為 `failed` 時，請將任務 ID 與回傳的原因，連同你的內部任務 ID 一併記錄。向使用者顯示可採取的下一步，例如檢查來源 URL 或上傳可讀取的 PDF，而不是直接暴露未經格式化的 API 錯誤。

## 設定實用的時間限制

使用符合你產品體驗的輪詢截止時間。在該截止時間停止輪詢，保留任務 ID，並讓背景工作程式或使用者觸發的重新整理稍後檢查最終狀態。

關於確切的回應欄位與失敗範例，請參閱 [API Reference](https://pdfcraft.ai/zh-Hant/api/)。