Shared API behavior
驗證、錯誤、重試與相容性
這些規則適用於所有 /v1 資源。各 endpoint 的欄位與非 2xx response 以執行中 OpenAPI 為準。
Request ID
X-Request-ID: req_partner_incident_0182每個 response 都有 request ID。正式整合記錄 method、公開 path、status、latency 與 request ID，不記錄含攝影機 URL 或 key 的 body。
錯誤信封
{
"error": {
"type": "invalid_request_error",
"code": "source_unreachable",
"message": "The source did not return a decodable frame before the timeout.",
"param": "input.url"
},
"request_id": "req_01..."
}程式依 type/code 處理；message 給人看，可以在不改版本時改善。
Idempotency
Idempotency-Key: partner-order-0182-source重試同一 mutation 時，使用相同 key 與語意相同的 body。不要把同一 key 拿去做不同工作。
重試
可安全重試 GET／HEAD、帶相同 Idempotency-Key 且文件標示可重試的 mutation，以及 408、425、429 與暫時性 5xx。409 只有在 error code 明確標成暫時衝突時才重試；不同 body 的 idempotency_key_reused 不能重試。使用 jitter 與 bounded exponential backoff，並遵守 Retry-After。
Cursor 與時間
GET /v1/sources?limit=100&after=<next_cursor>
{
"object": "list",
"data": [],
"has_more": false,
"next_cursor": null
}Source、Monitor、Incident、Webhook Endpoint 與 Delivery 列表的 limit 預設為 100、上限為 500。has_more 為 true 時，把 next_cursor 原封不動放入下一次的 after；cursor 綁定資源與篩選條件，修改、跨列表使用或改變篩選條件都會回傳 400 invalid_cursor。不要推算 page number 或排序 opaque ID。所有 JSON timestamp 使用 RFC 3339 UTC，且來源畫面時間與伺服器接收／事件建立時間分開。