错误码

BeatAPI 的每一次失败都用一组固定的错误码表示。程序判断请看错误码；错误信息是写给人看的一句话。两者都不会转述模型供应商返回给我们的任何内容——不含供应商名称、不含供应商的状态码、不含供应商的原始报错。联系支持时请保留 request_id。

失败出现在哪里

任务可能在两个时间点失败，表现不同：

1. 创建时。 请求在任务生成之前被拒绝。你会收到带 error 对象的 HTTP 错误，没有 data.id，不扣费。
2. 任务被接受之后。 POST 已返回 201 和 data.id，任务之后以 status: "failed" 结束。GET /v1/tasks/{task_id} 依然返回 200，失败原因在 data.error_code 和 data.error_message 里，为该任务预扣的额度会退回。

{
  "error": {
    "code": "content_policy_violation",
    "message": "The request was blocked by content moderation. Please change the prompt or the input and try again.",
    "request_id": "req_abc123"
  }
}

{
  "data": {
    "id": "task_8K2qA",
    "status": "failed",
    "error_code": "content_policy_violation",
    "error_message": "The request was blocked by content moderation. Please change the prompt or the input and try again."
  }
}

同一种失败在这两处的错误码相同，控制台用量日志里的错误行也是同一个码（content_policy_violation: The request was blocked…）。

错误码

processing_unavailable 和 rate_limit_exceeded 含义不同：rate_limit_exceeded 针对你的请求频率，意思是请放慢；processing_unavailable 表示模型此刻无法接单，你的请求本身没有问题。

重试策略

• 不要原样重试： content_policy_violation、bad_request、unauthorized、forbidden、insufficient_credits、idempotency_conflict。
• 等待后重试： rate_limit_exceeded、user_concurrency_exceeded（有 retry_after_seconds 时按其等待）、processing_unavailable。
• 退避重试： processing_timeout、processing_failed、result_transfer_failed、internal_error。使用指数退避并设置上限；失败的任务已退款，新的尝试只有成功才会产生费用。

变更记录

• 2026-09-23：任务接受后因参数不被接受或输入无法获取而失败，现在报 bad_request（原为 processing_failed）。创建时不再透传模型供应商的状态码：内容审核拒绝一律为 400 content_policy_violation，供应商不可用为 503 processing_unavailable。创建时余额不足为 402 insufficient_credits。