WebSocket Troubleshooting

Every WebSocket connection failure we've seen reported, with a recipe to fix it. Start from the close code if you have one; otherwise scan the symptom list.

Step 0 — Verify with curl first

Before debugging in code, run a raw curl handshake. If this works and your code doesn't, the problem is in your client, not the server.

curl --include --no-buffer \
  --header "Connection: Upgrade" \
  --header "Upgrade: websocket" \
  --header "Sec-WebSocket-Key: $(head -c 16 /dev/urandom | base64)" \
  --header "Sec-WebSocket-Version: 13" \
  --header "X-API-Key: $PARLAY_API_KEY" \
  "https://parlay-api.com/v1/ws/odds/baseball_mlb"

Expected first line: HTTP/1.1 101 Switching Protocols. If you get a 4xx instead, see the corresponding row below.

Close-code reference (with fix)

HTTP errors (before WebSocket upgrade)

403 Forbidden on handshake

Almost always means the API key wasn't recognized at the WAF / edge layer. Check:

• Are you hitting https://parlay-api.com (correct) vs http:// or an old domain?
• If using Cloudflare Workers / Lambda Edge / similar in your own stack, are you stripping the X-API-Key header in transit?
• Is your network egress from a country we don't serve? We're available globally; if you see geographic blocks, that's not us — likely your egress IP is on a deny list at your provider.

426 Upgrade Required

You hit a non-WebSocket endpoint with WebSocket headers. Double-check the URL path — common typo is /v1/odds/... (REST) vs /v1/ws/odds/... (WebSocket).

404 Not Found

Same — URL typo. The four valid URL prefixes are /ws/odds/, /ws/live/, /v1/ws/odds/, /v1/ws/live/. Anything else 404s.

"It connects, but I get no odds_update frames"

This is usually fine and not a bug. The collector only pushes when prices change. In quiet windows you can go 60+ seconds with nothing on the wire.

Quick check:

• Did you receive a connected frame? If not, you're not authenticated. Re-check the handshake.
• Did you receive an initial_state frame with count > 0? If count == 0, the sport has no events in scope right now (e.g. WNBA at 3am Eastern). Pick a sport with live coverage.
• Are you running this during off-hours for that sport? MLB is silent in the off-season; NBA props are silent between 3am and 9am Eastern. Look at commence_time in the snapshot — if no events tip in the next 24 h, the stream should be quiet.
• Are you behind a corporate proxy that buffers responses? Some proxies hold the WebSocket frames in transit, releasing them in batches every 30s. Test from a non-corporate network to confirm. See proxy issues below.

Proxy, VPN, and corporate-network issues

Symptoms: connection establishes fine, but frames arrive in irregular bursts (5–30 s gaps then a flood) instead of streaming smoothly.

Likely causes (in order of frequency):

1. HTTP proxy without WebSocket support. Older squid / forward-proxy setups don't pass Upgrade through cleanly. Tunnel via a corporate-approved HTTPS path if available, or fall back to SSE (which is plain HTTP).
2. Inspection proxy holding frames. Some enterprise DLP / TLS-inspection appliances buffer WebSocket payloads to scan them. Add parlay-api.com to your inspection bypass list.
3. NAT timeout shorter than our 30 s heartbeat. If your NAT kills idle TCP sockets at 20 s, you'll see disconnect-reconnect-disconnect. Configure NAT timeout > 60 s, or switch to SSE.
4. VPN with split-tunneling. Make sure parlay-api.com is in the tunnel set if you're behind a corporate VPN.

AWS Lambda / serverless gotchas

Don't open WebSocket connections inside Lambda function handlers — they get torn down when the function returns. Two viable patterns:

• Run a persistent EC2 / Fargate / Cloud Run worker that holds the WebSocket and posts updates to your Lambda via SQS / EventBridge / direct invoke.
• Use the SSE endpoint from a Lambda function with a longer timeout — same data feed, no persistent socket required, works for short-window scans.

Browser quirks

Safari closes the socket on tab background

Known Safari behavior on iOS / macOS — it pauses background tabs aggressively. Your client should reconnect on tab visibility change:

document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "visible" && ws.readyState !== WebSocket.OPEN) {
    ws = new WebSocket(URL);
    // re-wire onmessage / onclose / onerror
  }
});

Chrome devtools shows "Pending" forever

That's the WebSocket frame display, not an error. Click the WS request → Messages tab to see actual frames. The "Status: Pending" just means the connection is open (and pending close).

CORS errors

WebSocket bypasses CORS by spec — you should never see a CORS error on the upgrade itself. If you do, it's actually the page-load that's CORS-blocked, not the WebSocket. Make sure the JS file calling new WebSocket() loaded successfully first.

How to file a useful support ticket

If none of the above helps, please include the following at /support so we don't have to ping-pong:

• Key prefix (first 8 chars only — never the full key)
• The URL you connected to (verbatim, minus the key)
• Close code + reason if you got one
• Approximate timestamp (UTC ideally)
• Output of the curl smoke test above
• Client language + library + version

Median response time on Business+ tickets is under an hour during US business hours.