通用约定

请求格式

• 请求和响应都是 JSON，编码 UTF-8，请求头带 Content-Type: application/json。
• 服务端接口的请求体上限是 2 MB，超出返回 413。浏览器采集的单次请求上限是 64 KB。
• 一次请求可以批量提交多条事件；批量上限写在各接口页。

时间与时区

• 事件时间 time 用 Unix 毫秒时间戳。不传时以服务器收到的时间为准。
• 与服务器时间相差过大的事件会被改成到达时间，并在响应里给出警告，避免客户端时钟错误污染报表。
• 报表按项目设置的时区切分日期，见 日期与时区。

去重

为每条服务端事件带上唯一的 insert_id（如订单号）。网络重试导致的重复提交会按它去重，不会重复计数。

错误码

错误响应长什么样

失败响应都有 statusCode、message 和 code。校验失败多一个 issues，限流多一个 retryAfter（秒）：

401 BAD_API_KEY

{
  "statusCode": 401,
  "message": "API Key 无效",
  "code": "BAD_API_KEY"
}

400 VALIDATION

{
  "statusCode": 400,
  "message": "参数校验失败",
  "code": "VALIDATION",
  "issues": ["events.0.event: Required"]
}

429 RATE_LIMIT

{
  "statusCode": 429,
  "message": "操作过于频繁，请稍后再试",
  "code": "RATE_LIMIT",
  "retryAfter": 12
}

程序里请按 code 判断错误类型，不要依赖 message 的文字。

常见错误码

状态	代码	含义与处理
400	VALIDATION	请求体不符合格式。按 issues 里的字段修正后再发。
400	BAD_REQUEST	JSON 无法解析。检查请求体是否是合法 JSON。
401	NO_API_KEY	没有带密钥，或 Authorization 为空。
401	BAD_API_KEY	密钥无效、过期、已撤销，或没有绑定项目。
403	SCOPE_FORBIDDEN	密钥缺少该接口需要的权限范围，见 权限范围。
413	PAYLOAD_TOO_LARGE	请求体超过上限。拆成多批发送。
429	RATE_LIMIT	超过频率限制。等待 retryAfter 秒后再试。
500	INTERNAL	服务端异常。稍后重试；持续出现请联系支持。

浏览器采集是例外：它总是返回 202，被丢弃的事件不会以错误码返回，排查方法见 统计无数据。

速率限制

接口	限制
服务端行为事件	每把密钥每分钟 600 次请求，单次最多 1000 条事件
机器人访问记录、日志导入	按请求体大小和单次条数限制，见各接口页
浏览器采集	按访客、IP 和站点分别限流；超出部分静默丢弃，仍返回 202

站点每分钟可接收的浏览器事件数与套餐有关，见 套餐与额度。

超限后怎么办

1. 收到 429 后不要立即重试，至少等待 retryAfter 秒。
2. 采用指数退避，并给重试次数设上限。
3. 尽量批量发送：一次请求带多条事件，比多次单条请求更省额度。
4. 重试时保持同一个 insert_id，避免重复计数。