API 行為

處理錯誤、分頁與重連

用 AI 閱讀

這些規則適用於 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 路徑不代表其他產品入口也開放相同操作；本公開文件只涵蓋唯讀事件功能。

事件搜尋與串流範例