V2
通用约定
了解分页、幂等、并发控制、限流、公共路由和时间格式等通用约定。
通用约定
适用范围
本页汇总 V2 API 中跨资源、跨接口复用的请求和响应规则。具体对象字段、block 类型和错误码定义分别放在各自参考页。
核心定义
| 约定 | 说明 |
|---|---|
| 分页 | 默认 page_size 为 20，最大 100。 |
| 幂等 | POST /v2/pages 可通过 Idempotency-Key 复用请求结果。 |
| 并发控制 | PATCH /v2/pages/:page_id 可通过 ETag 和 If-Match 做乐观锁。 |
| 频率限制 | 生产环境入口按分钟限流，超过限制会返回 429 rate_limited。 |
| 公共路由 | /v2/openapi.json 和 /v2/openapi/meta 不需要 token。 |
| 时间格式 | 统一使用 ISO 8601 时间戳，通常以 UTC Z 结尾。 |
| 游标 | next_cursor 是不透明字符串，不要解析其内部结构。 |
字段说明或规则
分页
V2 统一使用游标分页。
| 字段 | 位置 | 说明 |
|---|---|---|
start_cursor | 请求 | 分页起点，首次请求可省略。 |
page_size | 请求 | 每页数量，默认 20，最大 100。 |
next_cursor | 响应 | 下一页游标，无更多数据时为 null。 |
has_more | 响应 | 是否还有下一页。 |
- 如果接口文档单独说明了不同默认值，以接口页为准
next_cursor只用于继续翻页，不承诺可读性has_more: false时，next_cursor应为null
Idempotency-Key
Idempotency-Key 是用于幂等创建的请求头，文档化支持的接口是 POST /v2/pages。
- 同一个 token、同一路由、同一个
Idempotency-Key和同一请求体，会返回相同结果 - 同一个
Idempotency-Key如果请求体不同，会返回409 idempotency_conflict - 建议使用 UUID v4
If-Match
If-Match 是用于并发控制的请求头，文档化支持的接口是 PATCH /v2/pages/:page_id。
If-Match的值应来自资源读取时返回的ETag- 如果资源自读取后被修改，再次写入会返回
409 conflict - 不传
If-Match时，页面更新会退化为 last-write-wins
频率限制
生产环境开发者 API 入口会做统一限流。当前配置的稳态额度是每分钟 120 次请求；超过限制时会返回 429 rate_limited。客户端应把 429 当成可重试错误，并使用退避策略重试。
限流响应可能包含以下响应头：
| 响应头 | 说明 |
|---|---|
Retry-After | 建议等待的秒数。 |
X-RateLimit-Limit | 当前限制窗口内的请求配额。 |
X-RateLimit-Remaining | 当前限制窗口内剩余请求数。 |
X-RateLimit-Reset | 当前限制窗口重置时间，通常是 Unix 时间戳。 |
这些响应头是否出现取决于实际网关返回；客户端不要依赖它们一定存在。没有 Retry-After 时，建议使用指数退避并避免立即重试。
公共路由
以下接口不需要 Authorization 头：
GET /v2/openapi.jsonGET /v2/openapi/meta
这两个路由用于生成工具链、缓存校验和自动化检测，不属于普通资源访问接口。
时间格式
V2 中所有时间字段都使用 ISO 8601 字符串。
- 时间戳示例：
2026-04-01T08:00:00.000Z - 日期字段如果只表达日期，仍然使用字符串表示，不要手动转成数字时间戳
- 需要时区的字段会显式带
time_zone
next_cursor
next_cursor 是跨接口复用的游标字段。
- 它是 opaque 值，不要尝试拆解、排序或推断内部偏移
- 只能原样传回给下一次请求
- 把它当成“翻页令牌”，不是业务主键
常见注意事项
- 分页默认值是统一约定，但少数接口会根据返回内容单独设定默认页大小。
Idempotency-Key解决的是重试幂等，不是权限问题。If-Match解决的是并发冲突，不是资源不存在问题。- 遇到
429 rate_limited时，不要并发重试；先等待Retry-After或按退避策略降低请求速率。