錯誤、冪等與安全重試

保持一次邏輯操作不變

付費建立介面要求 8–200 字元的 Idempotency-Key。生成一次後，與完整請求一起儲存；超時或斷線重試時複用兩者。

同一鍵與同一規範化請求會返回原操作；同一鍵換了請求內容則衝突。原請求仍在接受過程中時，可能返回可重試的“處理中”衝突。冪等記錄至少保留 24 小時，不要假設永久去重。

去重範圍包含帳戶、操作和 API Key 身份（MCP 對應 OAuth 客戶端）。更換 API Key 後，即使冪等字串相同，也可能建立新任務。建立結果不明時，應先找回已知任務 ID，再處理憑據輪換。

建立結果不明確時，應先找回原任務，不能悄悄換新鍵。確實要重新生成或修改請求時，應重新獲得批准，並使用新邏輯鍵。

讀取錯誤結構

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "param": null,
    "retryable": true,
    "request_id": "example-request-id",
    "details": {}
  }
}

這是結構示意，不承諾錯誤訊息文本完全相同。根據 HTTP 狀態和 error.code 分支處理，檢查 retryable，保留 request_id 供支援排查。不要記錄原始請求頭、圖片正文、提示詞或簽名 URL。

如何處理

無權訪問資源時，服務可能有意返回“未找到”。不要嘗試列舉他人的資源 ID。

給重試設定邊界

遵循 Retry-After（秒數或 HTTP 日期）；缺失時使用帶隨機抖動的指數退避。設定最大嘗試次數和總體截止時間。停止本地等待，不代表服務端已接受的任務也停止。

讀取操作可在臨時傳輸故障後重試。付費建立結果不明確時，只有已儲存冪等鍵且請求不變，才能重試。不要盲目重試沒有冪等保護的上傳或其他非冪等操作。

達到截止時間後，儲存已知任務 ID，稍後恢復。任務終態失敗時，先檢查部分產物，再決定重新匯出還是重新生成。

帳戶限額與排查

PROVIDER_CONTENT_REJECTED 目前覆蓋 Seedance 明確內容稽核拒絕的終態，不屬於應原樣自動重試的臨時錯誤。讀取任務的 credits.status、credits.refunded 和 credits.released；credits.charged 已是淨扣費，不要再減一次退分。確認稽核拒絕且尚無產物、匯出未開始時，一鍵任務返還原流程整筆點數。客戶端超時或匯出失敗不等同於這一條件，退分也不構成新一輪付費生成的授權。

通過 GET /account 獲取當前限制；響應中的限流頭可能反映當前計數視窗。多建 Key 不會增加帳戶容量。多個任務的輪詢應分散執行，避免所有客戶端同時突發請求。

向支援提供公共請求 ID、已知任務 ID、時間、錯誤碼和簡短描述。移除憑據和私有輸入。不完整結果見輪詢與下載，有界重試實現見 Python 示例。