错误处理

公共 API 的普通错误使用统一 envelope。code 是字符串，不等同于 HTTP 状态码；调用方应先判断 HTTP 状态，再记录业务 code 和 message。

例如，向一个不存在或无权访问的会话发送消息：

POST /api/v1/sessions/s-NOT-EXIST/messages HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY
Content-Type: application/json

{
  "content": "你好"
}

返回 HTTP 404：

{
  "code": "404",
  "message": "会话不存在",
  "data": null
}

HTTP 状态码

状态	语义
400	请求 schema、参数、Content-Type 或业务输入校验失败。
401	缺少凭据，或 Bearer 凭据无效、已删除、已刷新。
403	已认证，但没有资源或操作权限。
404	资源不存在或当前账号不可访问。
409	状态冲突。
429	请求频率或配额受限。
500	服务端内部错误。
503	消息运行所需服务暂不可用。

运行时还可能返回更细的字符串业务码，例如 4011 表示 Token 已过期，4031 表示仅管理员可访问，4091 表示 Token 余额不足，4092 表示配额已用尽，5021 或 5022 表示下游运行能力错误。不要根据错误消息文本编写控制流。

排错顺序

1. 检查请求路径是否以 /api/v1 开头，并确认方法正确。
2. 检查 Authorization 是否使用 Bearer raa-...，且 Key 未被刷新或删除。
3. 检查 JSON 请求是否设置 Content-Type: application/json，且没有 schema 未声明的额外字段。
4. 404 不代表资源一定不存在，也可能是资源对当前账号不可见。
5. 503 时不要假定任务已经执行；通过会话接口确认状态后再重试。