將轉換結果視為具狀態的任務,而非同步的檔案下載。當來源檔案過大、無法取得或格式錯誤時,這能讓你的產品保持穩定可靠。
安全地重試
僅重試可安全重複的請求。結果請求可使用指數退避進行重試。對於提交請求,請先保存成功回應所回傳的任務 ID,再嘗試再次提交。
處理終止性失敗
當任務為 failed 時,請將任務 ID 與回傳的原因,連同你的內部任務 ID 一併記錄。向使用者顯示可採取的下一步,例如檢查來源 URL 或上傳可讀取的 PDF,而不是直接暴露未經格式化的 API 錯誤。
設定實用的時間限制
使用符合你產品體驗的輪詢截止時間。在該截止時間停止輪詢,保留任務 ID,並讓背景工作程式或使用者觸發的重新整理稍後檢查最終狀態。
關於確切的回應欄位與失敗範例,請參閱 API Reference。