错误码

所有 API 错误以标准 HTTP 状态码 + JSON body 返回。

错误响应格式

{
  "error": "ErrActorRequired",
  "message": "actor field is required",
  "status": 400
}

HTTP	错误	说明
400	`ErrActorRequired`	`actor` 字段为空
400	`ErrModelRequired`	`model` 字段为空（引擎不做隐式选择）
400	`ErrKindRequired`	Memory 写入时 `kind` 为空
400	`ErrSessionRequired`	episodic 类 Memory 缺少 `session_id`
401	—	Token 缺失或无效
403	—	Token 权限不足
404	—	Cell / Session / 资源不存在
429	—	超出并发配额（`MaxConcurrentRuns` / `TokensPerMinute`）
503	—	Cell 处于 Cold 状态（响应含 `Retry-After: 5`）

HTTP	错误	说明
400	`ErrLayerNotWritable`	`environment` / `session` / `working` 层不可人工写入
400	`ErrLayerShared`	`consensus` 层不接受带 actor 的写入
400	`ErrLayerNamespaceRequired`	`agent_memory` 层缺少 namespace
400	`ErrUnknownLayer`	层名不存在
400	`ErrMemoryLayerScopeConflict`	`layer` 和 `scope` 同时指定
400	`ErrContentQualityRejected`	内容质量门控拒绝（如引擎状态前缀）
400	`ErrThreatPatternDetected`	威胁模式检测（凭据泄漏）

HTTP	错误	说明
400	`ErrVisionNotSupported`	请求含图片但模型未声明 Vision 能力
409	`ErrDegradedSecretOverwrite`	降级态密文保护：不可覆盖打不开的凭据