# 错误

错误响应结构、所有错误代码及重试时机。

来源：https://scifig.ai/zh/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 次，与网站共享。