API behavior
Handle errors, pagination, and reconnection
Use with AI
These rules apply to the v0.39 public read-only Event API. Record the error code, time, and operation so an administrator or integrator can investigate.
Respond to status codes
- 401: the key is missing, invalid, expired, or revoked. Stop retrying and check it locally.
- 403: insufficient_scope means missing permission; lan_source_forbidden means the device is outside the allowed network. Ask the administrator to review access.
- 404: check the path and event ID. event_image_not_found means no image is available. event_clip_not_available is expected because v0.39 does not provide event video.
- 400 invalid_cursor: restart from the first page with consistent filters. Do not edit the cursor.
- 409 stream_replay_limit_exceeded: too many events were requested for replay. Query history first.
- 429 or a temporary 503: wait as directed by Retry-After. Ask the administrator to check the service if failures persist.
Errors and request IDs
{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The API key is missing or invalid.",
"param": null
},
"request_id": "req_example"
}Use type and code in application logic; message is for people. API responses normally include X-Request-ID and request_id, but requests rejected by the LAN gateway may omit them. Support logs can include method, path, status, time, and request ID, without keys or event images.
Pagination
GET /v1/events?limit=100
{
"object": "list",
"data": [],
"has_more": false,
"next_cursor": null
}limit defaults to 100 and accepts 1–500. When has_more is true, pass next_cursor unchanged as after and keep the other filters unchanged. The final next_cursor may be null. It is a page cursor, not a permanent polling checkpoint.
Retries and SSE reconnection
Retry GET reads after temporary network errors or transient 5xx responses with increasing delays and a maximum wait. Honor Retry-After. Do not repeatedly retry 401, 403, or known unavailable paths. The public Event API has no writes and requires no mutation Idempotency-Key.
After an SSE disconnect, use the last successfully processed event sequence as after_sequence. Do not substitute the list’s next_cursor. Save processing progress and deduplicate by event id so reconnects do not repeat business actions.