錯誤總表

除了檔案下載端點(成功時回應是檔案本身)之外,所有錯誤回應都是 Content-Type: application/json,且至少包含一個 message 欄位;422 額外包含 errors 欄位(Laravel 標準驗證錯誤格式,鍵為欄位名、值為訊息陣列)。

狀態碼	意義	會發生在哪裡
401	未驗證或驗證失敗	缺 X-Api-Key header;Key 不存在/已撤銷;試用 Key 綁定的額度已過期(見〈驗證方式〉)
402	積分不足	建立任務時,付費餘額或試用額度剩餘額度不足以支付這次費用(見〈積分與計費〉)
404	找不到資源,或資源不屬於你	查詢/下載的任務 publicId 不存在或不屬於這支 Key 的帳號;下載端點的 key 不存在於該任務的 result 裡(見〈任務查詢與取件〉)
410	資源曾經存在,但已超過保留期或已被清除	下載端點:任務結果檔已超過表面保留期(files_expired),或物件已被物理刪除(見〈任務查詢與取件〉)
422	請求參數未通過驗證	建單的欄位驗證失敗;model 值查無對應模型(Unknown model alias: {model});images 內的 data URI 格式/base64/MIME/大小不合法(見〈圖生影片〉)
429	頻率或併發超限	短時間內超過 Key 的 QPS/日用量限制(見〈驗證方式〉);你名下同類型任務的待處理數已達上限(回應帶 Retry-After header,見〈圖生影片〉)

範例

缺少 API Key(401)

{ "message": "API key required." }

積分不足(402)

{ "message": "Insufficient credits to complete this charge." }

任務不存在或不屬於你(404)

{ "message": "Task not found." }

結果檔已過保留期(410)

{ "message": "File has expired." }

欄位驗證失敗(422)

{
  "message": "The duration field is required.",
  "errors": { "duration": ["The duration field is required."] }
}

背壓限制(429)

{ "message": "Too many pending tasks of this type; please retry later." }

回應同時帶 Retry-After header(秒數),建議依此值延後重試。