# 錯誤

錯誤響應結構、所有錯誤代碼及重試時機。

來源：https://scifig.ai/zh-Hant/docs/api/errors

## 響應結構

```json
{
  "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 次，與網站共享。