錯誤處理與安全重試

沒收到回覆，先保留原本的識別碼

連線中斷不代表請求失敗，伺服器可能已經接受並扣點。

• 台語翻譯：以相同 Idempotency-Key 和相同 text、audio 重送。
• 漫畫翻譯：以相同的每頁 requestIds、原始圖片位元組、目標語言與字型重送。
• 已取得工作 id：直接查詢 statusUrl，不必重新上傳。

每次新翻譯都應先產生並保存 UUID。重試同一份工作時不要重新產生 UUID；即使內容相同，新的識別碼也代表一份新工作，會再次計費。

相同識別碼搭配不同內容會收到 409 idempotency_conflict。改用其他有效金鑰不會改變同帳戶的重試結果。

請求錯誤格式

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account does not have enough credits."
  },
  "requestId": "6e8a5614-5e13-4f81-babc-04824b18b210"
}

程式應判斷 error.code，不要依賴英文訊息的完整文字。requestId 也會出現在 X-Request-ID 回應標頭，可提供給客服查詢。

HTTP 狀態	常見代碼	處理方式
400	invalid_request、invalid_json	檢查欄位、UUID、JSON、圖片內容與尺寸
401	invalid_api_key	修正或更換金鑰
402	insufficient_credits	補足 Plus 點數，再以原識別碼重試；Basic 點數不能用於 API
404	not_found	檢查端點、工作 ID 與帳戶；其他帳戶的工作也會回傳此錯誤
409	idempotency_conflict	檢查重試的內容是否一致；只有刻意建立新翻譯時才換識別碼
409	result_not_ready	先查詢工作進度，完成後再下載
410	result_expired	內容已過期，無法下載；舊識別碼不會產生新翻譯
413	request_too_large	縮小檔案、JSON 或減少圖片數
415	unsupported_media_type、unsupported_encoding	使用支援的內容類型，不壓縮請求本體
429	rate_limit_exceeded、queue_full	遵守 Retry-After，稍後使用原識別碼重試
503	service_unavailable	稍後使用原識別碼重試
500	internal_error	保存 X-Request-ID，以原識別碼重試或聯絡客服

翻譯失敗不是 HTTP 請求失敗

已接受的工作即使翻譯失敗，狀態查詢仍回傳 200，其中 status: "failed"，並附上 error.code 與退點資訊。圖片工作可能包含 translation_failed、translation_timeout 或 translation_cancelled；台語工作也可能因翻譯、語音產生、儲存失敗或處理中斷而失敗。

重送已失敗的工作會取得同一個失敗結果。若決定重新翻譯，請使用新識別碼，並視為新的付費工作。

查詢頻率與退避

每個帳戶每分鐘最多 30 次寫入請求、120 次讀取請求，所有金鑰共用。重送、狀態查詢與下載也計入請求次數；不扣點不代表不計入頻率限制。

工作尚未完成時，至少等待回應中的 Retry-After 秒數。連續遇到暫時性錯誤時，逐步增加等待時間並加入少量隨機延遲，避免所有工作同時重試。

不要把新建工作放進無限重試迴圈。請保存原識別碼與工作 ID，設定應用程式自己的等待上限；停止等待後仍可稍後查詢既有工作。