限制與錯誤

本頁總結跨 API 的通用規則。單一介面的必填欄位、生命週期和欄位語意仍以對應 API 頁面為準。

通用限制

專案	限制
請求 body大小	最大 32KB。
Gateway 產生 ID	32 位元小寫十六進位字串。
Channel 密碼	通常為 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 是 Gateway 受理和分發狀態，不是終端展示回執。

狀態碼	意義	典型原因	處理建議
`200`	請求已被 Gateway 處理	`success=true`，但仍需檢視 `accepted`	儲存返回的 ID 和 `op_id`。
`400`	請求校驗失敗	缺少必填欄位、未知欄位、欄位格式錯誤	對照 API 欄位表，檢查 JSON 和大小寫。
`401`	Gateway 級驗證失敗	私人 Gateway 開啟 `PUSHGO_TOKEN`，Bearer Token 缺失或錯誤	檢查 `Authorization: Bearer <token>`。
`404`	目標不存在	Channel、事件或實體不存在	檢查 `channel_id`、`event_id`、`thing_id`。
`413`	請求 body過大	JSON 超過 32KB	圖片使用 URL；減少 metadata 或 attrs。
`503`	分發未完整成功	provider、私人通道、佇列或下游暫時無法使用	檢視 Gateway 日誌、統計指標和佇列容量。