开发接口
错误处理
识别鉴权、权限、校验和资源不存在等稳定错误语义。
错误码
| 类型 | 含义 | 处理 |
|---|---|---|
unauthorized | 缺少、无效或已撤销的凭据 | 检查 Bearer Token |
forbidden | Key 缺少所需 Scope | 使用权限匹配的新 Key |
validation_failed | 字段或参数不合法 | 修正请求,不要原样重试 |
not_found | 资源不存在或不可见 | 检查 ID 与工作区 |
鉴权失败
优先确认环境变量已被 Agent 进程读取、Key 未撤销,并且 Header 使用 Bearer 方案。
重试策略
只有网络超时、限流或服务端暂时错误适合退避重试。鉴权、权限与校验错误需要先修正配置或请求。