API 行為

# 處理錯誤、分頁與重連

這些規則適用於 v0.39 公開唯讀事件 API。遇到問題時，先記下錯誤碼、發生時間與正在做的事，再交由管理員或整合人員排查。

## 依狀態碼處理

*   401：金鑰缺少、無效、過期或已撤銷。停止重試，先在本機核對金鑰。
*   403：insufficient\_scope 表示權限不足；lan\_source\_forbidden 表示裝置不在允許的網路。請管理員協助。
*   404：先核對路徑及事件 ID。event\_image\_not\_found 表示沒有圖片；event\_clip\_not\_available 是 v0.39 不提供事件影片的預期結果。
*   400 invalid\_cursor：重新從第一頁查詢，並保留相同的篩選條件；不要修改游標。
*   409 stream\_replay\_limit\_exceeded：要求補收的事件過多，先查詢歷史紀錄。
*   429 或暫時性 503：依 Retry-After 等待。持續失敗時請管理員檢查服務。

## 錯誤格式與請求 ID

```
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key is missing or invalid.",
    "param": null
  },
  "request_id": "req_example"
}
```

程式依 type 與 code 判斷，message 供人閱讀。API 回應通常帶 X-Request-ID 和 request\_id；LAN 入口直接拒絕的請求可能沒有。支援紀錄可包含方法、路徑、狀態碼、時間和請求 ID，不要包含金鑰或事件圖片。

## 分頁

```
GET /v1/events?limit=100

{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}
```

limit 預設 100，範圍為 1–500。has\_more 為 true 時，將 next\_cursor 原樣作為下一頁的 after，其他篩選條件不變。最後一頁的 next\_cursor 可能為 null；它是分頁游標，不是永久輪詢進度。

## 重試與 SSE 重連

GET 讀取遇到暫時網路錯誤或暫時性 5xx 時，可逐步延長等待時間後重試，設定等待上限並遵守 Retry-After。不要持續重試 401、403 或已知不可用的路徑。公開事件 API 沒有寫入操作，不需要寫入用的 Idempotency-Key。

SSE 斷線後，使用最後處理成功的事件 sequence 作為 after\_sequence。不要拿列表的 next\_cursor 代替。收到事件後先保存處理進度，以事件 id 去重，避免重連後重複處理。

新增回應欄位時，用戶端應保留相容性並忽略不需要的未知欄位。相同 /v1 路徑不代表其他產品入口也開放相同操作；本公開文件只涵蓋唯讀事件功能。

[事件搜尋與串流範例](https://watch.tensordynamics.org/developers/events?lang=zh)

---
Source: https://watch.tensordynamics.org/developers/api-behavior?lang=zh
More Watch guides: https://watch.tensordynamics.org/llms.txt