API 文件 · 可靠性

重試建議

哪些錯誤該重試、如何退避。

情況	是否重試	做法
網路逾時、連線中斷	是	以同一個 Idempotency-Key 重試
429 rate_limited	是	依 Retry-After 等待後重試
500 internal_error	是	指數退避，並使用同一個冪等鍵
422 asset_not_ready	是	等待素材變為 available
400 / 401 / 403 / 404 / 409	否	修正請求後再送出
402 額度或限額不足	否	補充額度、調整 Key 限額或 max_budget 後再送出
任務 failed	視失敗碼而定	參考任務失敗碼的建議做法；重新送出需使用新的冪等鍵

建議的退避方式：第一次等待 1 秒，之後每次 ×2，並加上 0–500 毫秒的隨機抖動，最多 5 次。平台內部已做了通道層級的重試與切換，你不需要為同一個任務重複送出。

Node.js

// 以業務端唯一 ID 作為冪等鍵：逾時重試不會重複建立任務
async function submit(order) {
  const key = `order-${order.id}-v${order.revision}`;
  for (let attempt = 0; attempt < 5; attempt++) {
    try {
      const res = await fetch("https://cn-api.aitoken.tools/v1/videos/generations", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.AITOKEN_API_KEY}`,
          "Idempotency-Key": key,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(order.payload),
      });
      if (res.status < 500 && res.status !== 429) return res.json();
    } catch {
      // 網路錯誤：繼續使用同一個 key 重試
    }
    await new Promise((r) => setTimeout(r, 2 ** attempt * 1000 + Math.random() * 500));
  }
  throw new Error("submit failed");
}