API behavior

# Handle errors, pagination, and reconnection

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.

Clients should tolerate additional response fields and ignore unknown fields they do not need. A shared /v1 prefix does not mean every product entry point exposes the same operations. This public guide covers read-only events.

[Event search and streaming examples](https://watch.tensordynamics.org/developers/events?lang=en)

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