> ## Documentation Index
> Fetch the complete documentation index at: https://docs.4casters.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 心跳

心跳用於保持會話存活。傳送帶 `requestTimeout`（單位為**秒**）的心跳 — 如果伺服器在該超時到期前未收到下一次心跳，**你的所有未成交訂單將被自動取消**。

通常在連線生命週期內按固定間隔傳送心跳（例如每 5 秒一次，超時 10 秒）。

<h2 id="request">
  請求
</h2>

<CodeGroup>
  ```json JSON theme={null}
  [
    "heartbeat",
    {
      "requestID": "YOUR_REQUEST_ID",
      "requestTimeout": 10
    }
  ]
  ```
</CodeGroup>

<ResponseField name="requestID" type="string">
  用戶端生成的識別碼；會在回應中回傳。若省略，伺服器會生成一個。
</ResponseField>

<ResponseField name="requestTimeout" type="number" required>
  伺服器在取消你的全部未成交訂單之前，應等待下一次心跳的秒數。必須大於 `0`。
</ResponseField>

<h2 id="response">
  回應
</h2>

伺服器回覆 `heartbeatAck`，其中包含伺服器時鐘和當前有效超時。

<CodeGroup>
  ```json JSON theme={null}
  {
    "requestID": "YOUR_REQUEST_ID",
    "data": {
      "type": "heartbeatAck",
      "serverTime": "2026-04-22T15:30:00.123456789Z",
      "timeoutSec": 10
    }
  }
  ```
</CodeGroup>

<ResponseField name="data.type" type="string">
  始終為 `heartbeatAck`。
</ResponseField>

<ResponseField name="data.serverTime" type="string">
  當前伺服器時間，RFC 3339 格式，納秒精度。
</ResponseField>

<ResponseField name="data.timeoutSec" type="number">
  回顯你傳送的 `requestTimeout`。
</ResponseField>

<h2 id="errors">
  錯誤
</h2>

如果 `requestTimeout` 缺失或 `<= 0`，伺服器回傳：

<CodeGroup>
  ```json JSON theme={null}
  {
    "requestID": "YOUR_REQUEST_ID",
    "error": "Invalid heartbeat timeout"
  }
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.