Troubleshooting

The CUIP SDK includes built-in error handling modules for common connection and authentication issues.
Below are typical scenarios and how they are managed internally.

Issue	Cause	Resolution
401 Unauthorized / 403 Forbidden	The API key is invalid, missing, or expired.	Ensure your CUIP API key is valid. When unauthorized access occurs, the SDK automatically triggers _handle_unauthorized() to display a clear message and terminate safely.
Invalid Stream ID	The stream_id parameter does not match any supported data channel.	Use one of the valid stream identifiers: spat-events, sdsm-events, bsm-events, srm-events, ssm-events, all-lidars-events, georgia-lidar-events, gs-realtime-zone.
Connection Timeout / WebSocket Error	The client failed to reach ws://cuip-api.research.utc.edu or the VPN is disconnected.	Verify VPN connectivity to CUIP’s internal network. Ensure ports 8080–8090 are open for your stream. The SDK automatically reconnects if the connection drops.
KeyboardInterrupt (Ctrl+C)	User manually stopped the stream.	No action needed. The SDK gracefully handles this through _handle_keyboard_interrupt() and exits cleanly.
Unhandled Exception or JSON Decode Error	Malformed or unexpected data in the WebSocket payload.	The SDK catches parsing errors within process_ws_stream(). Implement error-tolerant logic inside your callback (cb) to skip or log problematic messages.
No Data Output	The stream is connected but inactive.	Verify that the data source is currently broadcasting events. Confirm your callback function prints or logs incoming messages.