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 次，与网站共享。