错误

统一的错误结构，以及每个状态码在这里的确切含义。

任何失败都返回一个带 detail 字段的 JSON，HTTP 状态码说明这是哪一类失败。

{ "detail": "Insufficient quota: requested 8 GPUs, 2 available" }

绝大多数情况下 detail 是字符串。请求体校验是例外：FastAPI 返回数组，每个被拒的字段一条。

{
  "detail": [
    {
      "loc": ["body", "spec", "resources", "pools"],
      "msg": "List should have at least 1 item after validation",
      "type": "too_short"
    }
  ]
}

要渲染错误的客户端两种都得处理。loc 是出问题字段的路径，用点连接起来即可；msg 是值得展示给人看的那句。

​

状态码

状态码	在这里的含义	该怎么办
400	请求读懂了，但被拒绝。最常见的一类：JobSpec 不合法、引用写错、取值超出声明范围	看 detail，它会点名具体是哪一项
401	没带 token、格式不对，或者已过期	重新认证。不要拿同一个 token 重试
403	认证通过，但没有权限。管理员专属接口、读不了的数据集、不属于你的部署	重试没用，找管理员
404	没有这个作业 / run / 数据集 / 模型 / 部署——或者有，但不允许你知道它存在	检查 id
409	状态冲突：推广一个尚未 ready 的 revision、推送已存在的数据集版本、停止一个已经停了的作业	重新读当前状态再决定
411	需要 Content-Length 的上传没带这个头	补上
413	上传体超过部署上限，或提交的归档解压后超限	缩小打包内容，上限由 FORGE_MAX_UPLOAD_MB 决定
422	请求体没通过 schema 校验	按 detail[].loc 点到的字段改
429	被限流——登录尝试或设备码轮询	退避。设备流轮询不要快于每 5 秒一次
500	控制平面的缺陷	可以重试一次；仍然失败就带上响应和时间戳报缺陷
501	这套部署没有开启该功能	需要管理员开启
502	控制平面依赖的后端挂了：执行器、对象存储、OIDC 提供方	通常是瞬时的，退避后重试
503	控制平面活着，但有意不提供服务：维护模式，或升级前的排空	稍后重试。GET /api/version 仍然会响应

​

读懂一次被拒的提交

POST /api/jobs 在任何调度动作之前就会拒绝，detail 会点名是哪道闸拦下的。下面这几种值得认识：

Recipe 握手失败

提交里的 recipe.lock.json 和服务端 catalog 对不上——名字、版本、digest 或 framework.runtime_id 有差异。通常是平台发布了新的 recipe 版本，而你的实验还锁在旧版本上。

sf recipe status <exp> 看差异，sf recipe upgrade <exp> 应用它。

配额不足

申请的 GPU 数超过了账号能同时占用的上限。在队列里排队不是这个错误——排队的作业是已经被准入的。 这是在门口就被拒绝，只有管理员能改。

镜像仓库不在允许列表里

--image 指向的仓库主机不在部署允许的范围内。允许列表放在服务端是有意的：它是阻止提交去任意地方 拉代码执行的那道闸。

拒绝覆盖 entrypoint

spec.source.entrypoint 非空。entrypoint 归 recipe 所有，作业不能替换它。 确实要跑自己的命令，用 custom/custom recipe。

打包里有敏感文件

打包器发现了 .env、*.pem、id_rsa* 之类，拒绝生成归档——这一步在你本机就失败了，请求根本没发出去。 密钥通过平台的注入通道进入作业，不走工作目录。

一部分老代码路径抛出的错误文案目前仍是中文，正在随着相关代码被修改而逐步改成英文。 遇到这种情况，报缺陷时引用状态码和接口路径更可靠。