Firefly Nexus
控制台
文档目录

Errors

错误处理

Firefly API 使用标准 HTTP 状态码和统一 JSON 错误结构。保留 request ID 可以帮助平台快速定位一次调用。

同步错误响应

JSON
{
  "error": {
    "code": "insufficient_points",
    "message": "可用余额不足",
    "request_id": "req_018f47a26c667c71"
  }
}

创建请求尚未被接受时，HTTP 返回非 2xx。error.code 适合程序分支，request_id 用于联系支持时定位这次请求。

异步任务错误

任务已被接受后，即使最终生成失败，查询任务仍返回 HTTP 200，并通过 status=failed 和结构化 error 描述结果。

error.message 提供可安全展示的失败原因和处理提示，可用于指导用户调整输入或稍后重试。

JSON
{
  "id": "018f47a2-6c66-7c71-9d43-5e62cb80f120",
  "object": "aigc.task",
  "type": "image",
  "status": "failed",
  "model": "gpt-image-2-text-to-image",
  "created_at": "2026-08-02T04:00:00Z",
  "updated_at": "2026-08-02T04:00:08Z",
  "status_url": "https://api.fireflyfusion.ai/v1/aigc/tasks/018f47a2-6c66-7c71-9d43-5e62cb80f120",
  "output": [],
  "error": {
    "code": "generation_failed",
    "message": "生成失败，请稍后重新提交",
    "phase": "poll",
    "retryable": true
  }
}
  • phase 表示失败发生在请求、等待、提交、生成、结果检查或计费处理的哪个阶段。
  • retryable=true 表示可以调整输入或稍后重新提交。
  • retryable=false 表示必须先调整输入、补充余额或联系支持，不要盲目重提。
提交状态待确认

如果消息要求“请勿重复提交”，说明服务暂时无法确认任务是否已经受理。请保留 Firefly Task ID 并联系支持，重复提交可能产生新的任务。

失败任务如何计费

Firefly 只对完整成功的生成结果扣除金额，明确失败的任务不会收费。

  • 请求在创建任务前被拒绝：不暂扣，也不收费。
  • 任务创建后会按提交时锁定的价格暂扣金额；完整成功后才正式扣除。
  • 参数或内容被明确拒绝、生成失败、超时或结果检查失败：暂扣金额全部退回，实际收费为 0。
  • 提交状态待确认：预估金额继续保持锁定，等待状态更新；请勿重复提交。
  • 免费任务不会产生账单流水，但仍会保存任务与 Usage 交付记录。
不会部分扣费

任务只有完整成功或失败两种收费结果；失败任务的实际收费为 0。

常见状态码

HTTP处理建议
400请求参数无效。按模型文档修正字段、枚举或 URL。
401API Key 无效、过期或已吊销。检查 Bearer Header 或轮换密钥。
403当前 Key 无权执行该操作。检查凭证权限和访问限制。
402可用余额不足。先补充余额，再重新创建任务。
404模型或任务不存在。确认模型 ID 和任务是否属于当前账号。
422当前参数组合暂不可用。按模型文档调整参数或稍后重试。
503服务暂时不可用。等待后使用指数退避重新提交。

任务错误码

error.code处理建议
invalid_parameters调整模型参数后重新提交。
content_rejected调整提示词或输入素材后重新提交。
insufficient_points先补充足够余额，再创建新任务。
rate_limited等待当前运行任务完成，再退避重试。
model_busy模型当前繁忙，稍后退避重试。
generation_failed生成过程失败，可以稍后重新提交。
task_timeout任务处理超时，可以稍后重新提交。
service_unavailable服务暂不可用；以响应中的 retryable 为准。
internal_error平台处理异常；退避重试，持续发生时联系支持。

哪些错误可以重试

同步请求遇到网络中断、超时和 503 时，先在 API 请求记录中确认是否已经受理，再决定是否退避重提；重复提交会创建新任务。异步任务终态直接遵守 error.retryable；400、401、402、403、404 和 422 需要先修正请求或账户状态。

不要泄露凭证

联系支持时只提供 request ID、任务 ID、时间和错误代码，不要发送完整 API Key。