# 错误、权限与环境

| HTTP / code | 已核分支 |
| --- | --- |
| 400 / 2 | 参数/候选不合法；不满足同工作区绑定资格的ErrAgentReadOnly当前也经skill错误默认分支映射400，不能机械写成403。 |
| 404 / 3 | 原任务、owner、manifest、native候选或技能引用不可用的部分分支；消息使用skill not found，不公开内部缺失层次。 |
| 409 / 4 | 同预留ID存在但内容摘要或创建者不匹配等重复冲突。 |
| 409 / 9并带绑定失败reason | 技能已保存、后续绑定失败；reason/domain/saved_skill_id用于恢复。code9本身不够区分所有冲突。 |
| 403 / 5 | skill只读或授权拒绝分支；绑定阶段拒绝还可能包为409保存后绑定失败。 |
| 503 / 15 | 授权或技能依赖不可用分支；不是所有绑定失败都透传503。 |
| 500 / 1 | 绑定错误本地化异常等显式分支；不保证此时附saved_skill_id。 |

成功数字code0/data；普通skill错误为code/message，绑定失败增加details。身份校验发生在handler之前，可用字符串code/msg，不统一成数字错误。未知错误当前还可能由skill错误默认分支映射400并带错误文本，不能替它写统一500。

```json
{
  "code": 9,
  "message": "The skill was saved, but could not be added to this agent. Retry to finish adding it.",
  "details": {
    "reason": "SKILL_CREATOR_BINDING_FAILED",
    "domain": "moi-core.catalog.agent-resource",
    "saved_skill_id": "skill-example"
  }
}
```

message按服务端语言返回，上例为en-US目录值；用details.reason判别绑定失败，不硬匹配本地化消息。无论何种错误或超时，保存状态不明时均先回查原候选。
