# 错误、幂等与恢复

## GraphQL 错误

errors[].extensions.code 为稳定类别，reason 为具体拒绝原因。

| code / reason | 含义与处理 |
| --- | --- |
| INVALID_ARGUMENT / SCHEMA_VALIDATION | 输入不符合 schema；不要猜测替代输入 |
| CONFLICT / NAME_TAKEN | 等价名称已注册；不能自动认领其他主体资源 |
| MANIFEST_NAME_MISMATCH | release 校验失败，包名必须等于注册名 |
| UNAUTHENTICATED / FORBIDDEN | 当前身份、scope 或 ownership 不足 |
| NOT_FOUND | 不存在或无权知道存在性 |
| IDEMPOTENCY_KEY_REUSED | 同主体同 ID 提供不同 payload |
| CONFLICT / REVISION_CONFLICT | CAS 冲突，读取当前事实后再决定 |
| LEASE_EXPIRED | worker 旧 attempt 无权完成当前任务 |
| UNAVAILABLE | 依赖或响应无法确认，保留 ID 并查询 |

## 状态不是同一事实

receipt 为 accepted/applied/rejected/unknown。release 经 validating、pending_review 后才能 published，
也可能 rejected 或 yanked。accepted 不证明应用，applied 也不必然证明公开可下载。

## 幂等与未知效果

每个副作用命令必须有稳定 command_id；同主体同 ID 同 payload 重放原 receipt，并重新鉴权。
返回超时、取消或没有查询到 receipt，不证明上传或写入未发生。
先核对原操作、release 和字节身份，再继续原操作；禁止换 ID 盲重试。
有 expected_revision 的命令不能覆盖后来修改。worker 使用服务端时间 lease 和 fence。