错误码

查看 V2 API 的统一错误响应结构和所有错误码定义。

错误码

适用范围

本页只定义 V2 API 的统一错误模型和错误码枚举。各接口如何触发这些错误、如何补充参数校验信息，放到对应接口页说明。

核心定义

错误码	HTTP 状态码	说明
`validation_error`	400	参数校验失败或请求格式不合法。
`unauthorized`	401	token 无效、过期或缺失。
`forbidden`	403	scope 不足或资源不可访问。
`not_found`	404	资源不存在。
`conflict`	409	乐观锁冲突或资源版本不一致。
`idempotency_conflict`	409	幂等键对应了不同请求体。
`rate_limited`	429	触发限流。
`unsupported_filter`	400	不支持的 filter 结构或操作符。
`unsupported_sort`	400	不支持的排序字段或排序方式。
`unsupported_block_type`	400	不支持的 block 类型。
`internal_error`	500	服务端内部错误。

字段说明或规则

统一错误响应结构

所有错误响应都使用同一外壳。

{
  "object": "error",
  "status": 400,
  "code": "validation_error",
  "message": "parent.page_id is required",
  "request_id": "req_xxx",
  "details": [
    {
      "path": "parent.page_id",
      "reason": "required"
    }
  ]
}

字段	说明
`object`	固定为 `"error"`。
`status`	实际 HTTP 状态码。
`code`	V2 错误码枚举。
`message`	可直接展示给开发者的错误说明。
`request_id`	请求追踪 ID。
`details`	可选的补充错误明细。

`details`

details 通常用于参数校验场景。

path 指出出错字段
reason 说明出错原因
limit 和 actual 只在超限场景出现

403 的语义

forbidden 既可能表示 scope 不足，也可能表示资源不可访问。

scope 不足时，message 通常会写明缺少的 scope
资源不可访问时，message 会说明当前 bot 没有访问该资源的权限

409 的语义

conflict 用于资源版本冲突
idempotency_conflict 用于同一个幂等键对应了不同请求体

429 的语义

rate_limited 表示请求频率超过限制。生产环境开发者 API 入口当前稳态额度是每分钟 120 次请求。

如果响应包含 Retry-After，按该秒数等待后再重试。
如果响应包含 X-RateLimit-Limit、X-RateLimit-Remaining 或 X-RateLimit-Reset，可以用它们调整客户端节流策略。
不要对 429 做无等待的立即重试，否则可能持续触发限流。

常见注意事项

不要只依赖 message 做程序分支，应该优先判断 code。
request_id 是排查问题时最重要的关联字段之一。
details 不是所有错误都有，代码里应当按可选值处理。

错误码

错误码