# 错误码 (/docs/api/native/vault/errors)



错误响应体统一为下面的形状；code 是稳定的错误码，message 给人读。

```json
{
  "request_id": "req_example",
  "error": {
    "code": "SECRET_CONFLICT",
    "message": "A secret named GITHUB_TOKEN already exists",
    "kind": "validation_failure",
    "recovery": "none",
    "retryable": false
  }
}
```

错误体包含 request\_id，可用于定位请求。兼容接口使用下列错误形状；409 的类型为 conflict\_error，不可重试的错误带 x-should-retry: false。

```json
{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "A credential with this name already exists"
  },
  "request_id": "req_example"
}
```

| 错误码 | HTTP | 含义、触发条件与处理 | kind | recovery | 可重试 |
| --- | --- | --- | --- | --- | --- |
| VAULT_NOT_FOUND | 404 | 库不存在或不属于当前账户；检查库 ID | validation_failure | none | 否 |
| SECRET_NOT_FOUND | 404 | Secret 不存在，包括用非法名称查找；检查名称或 ID | validation_failure | none | 否 |
| AUTHORIZATION_NOT_FOUND | 404 | 授权或确认链接不存在；重新发起授权 | validation_failure | none | 否 |
| SECRET_CONFLICT | 409 | 创建时名称已占用；更换名称或更新已有 Secret | validation_failure | none | 否 |
| VAULT_INVALID_STATE | 409 | 向已归档的库或 Secret 写入；改用有效资源 | validation_failure | none | 否 |
| VAULT_LIMIT_EXCEEDED | 400 | 超过有效 Secret 数量上限；先清理不用的 Secret | validation_failure | none | 否 |
| INVALID_PARAMS | 400 | 字段、名称、域名、metadata、分页或回跳地址无效；修正请求 | validation_failure | none | 否 |
| SECRET_KIND_MISMATCH | 400 | 对 static Secret 续期或执行不匹配种类的操作；使用 OAuth Secret | validation_failure | none | 否 |
| VALIDATE_UNSUPPORTED | 400 | 对 static Secret 校验；校验仅支持 OAuth Secret | validation_failure | none | 否 |
| SECRET_TOO_LARGE | 413 | 值超过 16384 字节；缩小值后重试 | validation_failure | none | 否 |
| RATE_LIMITED | 429 | 一分钟内超过授权或校验额度；等待下一窗口 | rate_limit | wait_then_retry | 是 |
| AUTHORIZATION_EXPIRED | 410 | 授权链接超过 30 分钟或已使用；重新发起授权 | validation_failure | retry_from_user | 否 |
| OAUTH_DISCOVERY_FAILED | 400 | 无法发现服务方 OAuth 配置；检查资源地址 | validation_failure | continue_from_problem | 否 |
| OAUTH_REGISTRATION_UNSUPPORTED | 400 | 服务方不接受自动客户端注册；手动添加凭据 | validation_failure | continue_from_problem | 否 |
| OAUTH_ISSUER_MISMATCH | 400 | 授权服务器与预期不一致；重新检查服务地址 | provider_upstream | retry_from_user | 否 |
| OAUTH_STATE_INVALID | 400 | 回调 state 缺失、无效或重放；重新发起授权 | validation_failure | none | 否 |
| OAUTH_EXCHANGE_FAILED | 502 | 服务方拒绝授权码换令牌；重新授权 | provider_upstream | retry_from_user | 否 |
| NOT_IMPLEMENTED | 501 | 功能尚不支持；使用文档列出的替代方式 | execution_failed | none | 否 |