错误和限制

API 响应使用稳定的 envelope，方便客户端区分网络失败和业务错误。

错误结构

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "insufficient credits",
    "request_id": "req_...",
    "details": {}
  }
}

普通用户页面只展示简洁失败信息。管理员页面和日志可以保留 worker、provider、对象存储等详细错误。

未完成任务上限

API 用户可以按滚动窗口限制未完成任务数。未完成任务包含排队中和处理中任务。这样可以保护队列，同时不需要设置严格 QPS 限制。

容量行为

GPU 容量紧张时，平台应把符合条件的任务接收入队并返回队列状态。硬性安全上限仍然要保护数据库、队列、对象存储和 GPU 调度器。

幂等

每次创建任务都必须发送唯一的 Idempotency-Key Header。创建结果不确定时，使用相同 key 和完全相同的 payload 重试；相同 key 对应不同 payload 时会返回冲突错误。