WebSocket API Overview
Learn how to establish and maintain real-time connections with Pragma’s WebSocket API
WebSockets provide a persistent connection between your application and Pragma’s servers, allowing for real-time data streaming with minimal latency.
Connection Endpoints
We recommend using the Development endpoint while building and testing your application.
We recommend using the Development endpoint while building and testing your application.
Only switch to the Production endpoint when your application is fully tested and ready for deployment.
Authentication
All WebSocket connections are currently public and open without authentication.
In the near future, WebSocket connections will require authentication using an API key similar to the REST API. We recommend designing your implementation with this upcoming change in mind.
Connection Management
Connection Lifecycle
Understanding how to properly establish, maintain, and close WebSocket connections is essential for reliable real-time data streaming.
Reconnection Strategy
Implement proper reconnection logic to handle network interruptions and server-initiated disconnects gracefully.
Connection Limits
Byte Rate Limiting
Byte Rate Limiting
KB per second limit
Each IP address is limited to 256 KB per second of data transmission
Connections exceeding this limit are automatically closed without warning
Rate limits are tracked and enforced per unique IP address. Consider this when deploying multiple applications or services from the same origin.
Inactivity Timeouts
Inactivity Timeouts
Inactivity timeout
Connections automatically close after 60 seconds of inactivity
Recommended Practice
Send a ping message every 30 seconds to keep the connection alive
This timeout prevents resource consumption from idle connections and ensures efficient server utilization.
Best Practices
Implement proper error handling
Always include robust error handling and reconnection logic in your WebSocket implementation. Network disconnections and server-side issues can occur, and your application should gracefully recover from these scenarios.
Use ping/pong messages
Send regular ping messages (every 30 seconds) to keep the connection alive and detect stale connections early.
Monitor connection health
Track connection state and performance metrics in your application to ensure reliable data delivery and prompt detection of issues.
Implement backoff strategy
When reconnecting after failures, use an exponential backoff strategy to avoid overwhelming the server during outages.
Common Issues & Troubleshooting
Connection Closed Unexpectedly
Connection Closed Unexpectedly
Possible causes:
- Rate limit exceeded (256 KB/s)
- Inactivity timeout (60 seconds without messages)
- Server maintenance or restarts
Solution: Implement reconnection logic with exponential backoff. Ensure you’re sending ping messages every 30 seconds to keep the connection alive.
Message Format Errors
Message Format Errors
Possible causes:
- Incorrectly formatted JSON messages
- Missing required fields
- Invalid subscription parameters
Solution: Validate all outgoing message formats against the API documentation. Log and inspect error responses from the server.
High Latency
High Latency
Possible causes:
- Network congestion
- Geographic distance from server
- Client-side processing delays
Solution: Consider using a closer geographic endpoint if available. Optimize client-side message processing to reduce delays.