Troubleshooting

Work from the outside in: confirm the Xirsys API request, inspect signaling, then inspect ICE candidate gathering and connectivity. Capture exact timestamps, channel names, HTTP statuses, and sanitized response bodies before retrying.

REST API Requests

• 401 or unauthorized: verify the account identifier and secret, confirm the Basic auth value is created as IDENT:SECRET, use HTTPS, and make the request from the backend.
• Channel or namespace error: confirm the channel exists and that the complete, case-sensitive channel name matches the dashboard.
• 400 response: inspect the returned JSON, HTTP method, content type, query string, and request body. For TURN geo routing, both geo=1 and a valid public user_ip are required to apply the hint.
• 5xx response: check the Xirsys status page, retry transient failures with capped exponential backoff and jitter, and retain a sanitized response for Support.

Never include authorization headers, API secrets, TURN credentials, or signaling tokens in screenshots, tickets, or ordinary logs.

WebSocket Signaling

1. Fetch a current host with GET /_host?type=signal.
2. Create a fresh peer token with PUT /_token/{channel}?k={peer-id}.
3. Connect to the exact returned host plus /v2/{encoded-token}.
4. Wait for the WebSocket open event before sending.
5. Confirm both peers use tokens for the same channel and unique simultaneous peer IDs.
6. For private traffic, confirm m.t exactly matches the remote token's peer ID.

A user packet needs top-level t, m, and p; m.f and m.o are required. The token selects the channel. Without m.t, a message is broadcast to every other connected subscriber on the channel; the sender does not receive an echo.

Use JSON heartbeats such as {"t":"ping","ts":1721846400000} and expect a matching pong. Do not include m or p in heartbeat packets. After repeated missed pongs, close the socket and reconnect with backoff using a fresh host and token.

ICE and TURN

Verify the API result before constructing RTCPeerConnection:

const iceServers = data.v.iceServers; // Response from a request using webrtc=1
const pc = new RTCPeerConnection({ iceServers });

pc.addEventListener('icecandidateerror', event => {
  console.error('ICE candidate error', event.errorCode, event.errorText);
});

pc.addEventListener('iceconnectionstatechange', () => {
  console.log('ICE state:', pc.iceConnectionState);
});

• Request temporary credentials shortly before creating a peer connection. The default credential lifetime is 60 seconds.
• Credential expiry limits authentication of a new TURN allocation; it does not automatically terminate an already established allocation or call.
• With webrtc=1, confirm v.iceServers is an array containing an object with urls, username, and credential. The older format=urls response is a single object and must be wrapped in an array.
• To test relay connectivity, temporarily set iceTransportPolicy: "relay" and confirm a relay candidate pair is selected.
• For calls near users but far from your backend, use TURN end-user geo routing.

Firewall and Network Checks

Allow outbound DNS and connections to the hostnames returned by Xirsys. Common TURN URLs use UDP or TCP ports 80 and 3478, and TURN over TLS uses TCP ports 443 and 5349. Use the published Xirsys IP Allowlist if destination IP allowlisting is required.

Test from the affected network, not only from an office or developer connection. VPNs, carrier NAT, TLS interception, UDP blocking, browser privacy settings, and enterprise proxies can change ICE behavior.

Useful Diagnostics

• Chrome and Chromium: open chrome://webrtc-internals before reproducing the call.
• Browser developer tools: inspect REST responses, WebSocket frames, console errors, and timing.
• Application telemetry: record state transitions, selected candidate types, region, and sanitized Xirsys error envelopes.
• Packet capture tools such as Wireshark: confirm DNS resolution and whether expected UDP/TCP traffic leaves the client network.

Contact Support

If the problem remains, contact experts@xirsys.com. Include the UTC time range, affected channel, account identifier, client region and network type, browser/platform version, Xirsys gateway, HTTP status and sanitized response, signaling close code, and relevant ICE state transitions.

Do not send your API secret, Basic authorization header, temporary TURN credential, or full signaling token.