API 參考文件
錯誤
錯誤響應結構、所有錯誤代碼及重試時機。
響應結構#
{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Not enough credits.",
"request_id": "a698a9af-0685-4557-9b29-ca57637748f9",
"details": { "top_up_url": "https://scifig.ai/pricing?utm_source=api" }
}
}依據 error.code 和 details.reason 處理，不要依據可能變化的 message。響應不包含內部診斷資訊。
代碼#
| 代碼 | HTTP | 含義 | 重試 |
|---|---|---|---|
| UNAUTHORIZED | 401 | 憑證缺失或無效。 | 否；請修改請求或使用新金鑰 |
| ACCOUNT_UNAVAILABLE | 401 | 此帳戶無法使用 API。 | 否；請修改請求或使用新金鑰 |
| SCOPE_DENIED | 403 | 此憑證未授予所需權限。 | 否；請修改請求或使用新金鑰 |
| INVALID_REQUEST | 400 | 請求無效。 | 否；請修改請求或使用新金鑰 |
| IDEMPOTENCY_KEY_REQUIRED | 400 | 需要 Idempotency-Key 請求標頭（1–255 個可見 ASCII 字元）。 | 否；請修改請求或使用新金鑰 |
| IDEMPOTENCY_CONFLICT | 409 | 此 Idempotency-Key 已用於不同的請求。 | 否；請修改請求或使用新金鑰 |
| IDEMPOTENCY_IN_PROGRESS | 409 | 使用此 Idempotency-Key 的請求仍在處理中。 | 是，使用相同的 Idempotency-Key |
| NOT_FOUND | 404 | 未找到。 | 否；請修改請求或使用新金鑰 |
| REVISION_CONFLICT | 409 | 圖表或流程圖任務目前無法編輯：NOT_LATEST_REVISION、EDIT_IN_PROGRESS，或父任務仍執行時的 PARENT_JOB_RUNNING。 | 僅 PARENT_JOB_RUNNING 可在 Retry-After 後使用相同金鑰重試。其他情況請換新金鑰編輯最新版本 |
| PAYLOAD_TOO_LARGE | 413 | 請求體過大。 | 否；請修改請求或使用新金鑰 |
| INSUFFICIENT_CREDITS | 402 | 點數不足。 | 否；請修改請求或使用新金鑰 |
| CONTENT_REJECTED | 422 | 內容政策拒絕了請求。建立請求時以 422 回傳；任務執行期間被拒絕，則以失敗任務的 error.code 回傳；兩種情況均返還點數。 | 否；請修改提示詞或輸入，並使用新金鑰 |
| PLAN_REQUIRED | 403 | 你的方案不包含此選項。 | 否；請修改請求或使用新金鑰 |
| RATE_LIMITED | 429 | 請求數、每小時任務數、每日轉換數或上傳數過多；details.reason 說明具體原因。 | 是，使用相同的 Idempotency-Key |
| CONCURRENCY_LIMITED | 429 | 此帳戶執行中的任務過多。 | 是，使用相同的 Idempotency-Key |
| SERVICE_UNAVAILABLE | 503 | 服務暫時不可用。請使用相同 Idempotency-Key 重試。 | 是，使用相同的 Idempotency-Key |
| TASK_FAILED | 502 | 任務失敗，點數已返還。請傳送新請求（使用新的 Idempotency-Key）重試。 | 否；請修改請求或使用新金鑰 |
| INTERNAL_ERROR | 500 | 內部錯誤。 | 是，使用相同的 Idempotency-Key |
INVALID_REQUEST 可在相關資訊可用時包含 details.reason、details.field 或 details.issues。請求體超出限制時（JSON 為 256 KB，上傳遵循檔案大小限制），回傳 413 PAYLOAD_TOO_LARGE。只有 INSUFFICIENT_CREDITS 攜帶 details.top_up_url。任務建立後，建立請求若失敗（429、503、409 IDEMPOTENCY_IN_PROGRESS 或 500 INTERNAL_ERROR），details.job_id 標識該任務：請用相同 Idempotency-Key 重試或輪詢 GET /jobs/{job_id}，不要使用新金鑰。
失敗任務中的代碼#
已建立但隨後失敗的任務回傳 status: "failed" 和 error 物件。除上述代碼（用於拒絕請求）外，error.code 還可能為：
| error.code | 含義 | 處理方式 |
|---|---|---|
| TASK_TIMED_OUT | 任務超時，點數已返還。插圖產生或編輯可能攜帶 late_delivery_until：在此時間之前，結果仍可能免費交付。 | 繼續讀取任務直到 late_delivery_until；否則請用新金鑰傳送新請求 |
| CONTENT_REJECTED | 任務執行期間，內容政策拒絕了結果，點數已返還。在建立時請求本身被拒絕，則以 422 回傳相同代碼。 | 修改提示詞或輸入，並使用新金鑰 |
| ADMISSION_INCOMPLETE | 可重試錯誤阻止任務啟動，未消耗點數。 | 使用相同 Idempotency-Key 傳送相同請求 |
| TASK_NOT_FOUND | 任務已被接納，但已找不到對應的執行任務。 | 使用新金鑰傳送新請求 |
| TASK_FAILED | 任務失敗，點數已返還。沒有獨立公開代碼的引擎錯誤統一為 TASK_FAILED；引擎代碼位於 details.reason。 | 使用新金鑰傳送新請求 |
| INTERNAL_ERROR | 任務失敗但未報告原因，點數已返還。 | 使用新金鑰傳送新請求 |
429 的原因#
- 請求過多：每個憑證每分鐘 20 次建立請求、每個帳戶每分鐘 40 次建立請求、每個憑證每分鐘 120 次讀取請求。
Retry-After指示視窗重置前的等待時間；不包含details.reason。 - 最近一小時啟動的任務過多：每個帳戶最多 200 個，與網站共享。
Retry-After: 30。 - 執行中任務過多：
429 CONCURRENCY_LIMITED，按方案限制並與網站共享（參閱GET /credits）。Retry-After: 30。 - 每日 200 次免費 PNG、PDF、TIFF 和 PPTX 轉換額度已用完：
details.reason = DAILY_CONVERSION_LIMIT，Retry-After指示每日視窗重置前的等待時間。 - 上傳過快：
details.reason = UPLOAD_RATE_LIMITED（POST /files的圖片和遮罩、流程圖附件、圖表資料），對應網站每分鐘上傳限制。 - 每日上傳過多：
details.reason = UPLOAD_DAILY_LIMIT_REACHED（流程圖附件和圖表資料），對應網站每日上傳限制。 - 文字識別：每個帳戶每 15 分鐘 20 次，與網站共享。