限制与错误

本页汇总跨 API 的通用规则。单个接口的必填字段、生命周期和字段语义仍以对应 API 页面为准。

通用限制

项目	限制
请求体大小	最大 32KB。
Gateway 生成 ID	32 位小写十六进制字符串。
频道密码	通常为 8-128 字符。
`op_id`	1-128 字符，只允许字母、数字、`_`、`:`、`-`。
`images`	最多 32 项，每项 URL 最大 2048 字符。
`tags`	最多 32 项，每项最大 64 字符，trim 后去重。
`metadata`	只支持标量值；key 最大 64，value 最大 512。
`attrs`	对象补丁；`null` 表示删键；复杂嵌套应避免。
`ttl`	Unix 毫秒时间戳；provider 投递 TTL 会被裁剪到最大约 28 天。
未知字段	原生 Message、Event、Thing 和 MCP 工具参数都采用严格解析，未知字段会返回 400。

成功：

{
  "success": true,
  "data": {
    "accepted": true
  },
  "error": null,
  "error_code": null
}

失败：

{
  "success": false,
  "data": null,
  "error": "human readable message",
  "error_code": "machine_readable_code"
}

自动化脚本应优先判断 success 和 error_code，不要只依赖自然语言错误信息。

success=true 表示 Gateway 已处理请求。accepted=true 表示 Gateway 已进入分发流程。

它不保证：

因此，accepted 是网关受理和分发状态，不是终端展示回执。

状态码	含义	典型原因	处理建议
`200`	请求已被 Gateway 处理	`success=true`，但仍需查看 `accepted`	保存返回的 ID 和 `op_id`。
`400`	请求校验失败	缺少必填字段、未知字段、字段格式错误	对照 API 字段表，检查 JSON 和大小写。
`401`	网关级鉴权失败	私有 Gateway 开启 `PUSHGO_TOKEN`，Bearer Token 缺失或错误	检查 `Authorization: Bearer <token>`。
`404`	目标不存在	频道、事件或实体不存在	检查 `channel_id`、`event_id`、`thing_id`。
`413`	请求体过大	JSON 超过 32KB	图片使用 URL；减少 metadata 或 attrs。
`503`	分发未完整成功	provider、私有通道、队列或下游暂时不可用	查看 Gateway 日志、统计指标和队列容量。