---
title: Networking & API Access
description: >-
  Fix connectivity issues, CORS errors, WebSocket failures, and firewalls when
  using the platform.
tags:
  - troubleshooting
  - network
---

## Quick checks

Before investigating specific issues, try these general steps:

1. **Check platform health.** `curl https://www.ivybiosciences.com/api/health` returns the status of the database, storage and cache checks, and it needs no sign-in. When you're signed in, the `/health` page shows the same checks.
2. **Try an incognito window.** This rules out interference from extensions.
3. **Disable VPN/proxy temporarily.** If the issue disappears, your VPN or proxy is the cause.
4. **Try a different network.** Switch from corporate Wi-Fi to a mobile hotspot to isolate network-level issues.

## WebSocket connection failures

Job progress comes from the compute orchestrator over WebSocket, but the browser doesn't open that WebSocket. The server holds it and relays each job's events to the workspace as an SSE (Server-Sent Events) stream on this site, `/api/v1/jobs/[jobId]/events`. SSE runs over ordinary HTTPS, so a proxy that blocks WebSocket upgrades doesn't affect the workspace.

A `WebSocket connection to 'wss://...' failed` error in the console therefore comes from your own script or an extension, not from the workspace. If you connect to the orchestrator's WebSocket yourself (see [WebSocket streaming](/docs/api/realtime-websocket)) and it fails:

| Cause | Diagnosis | Fix |
|-------|-----------|-----|
| Corporate firewall blocks WebSocket | Only happens on corporate network | Ask IT to allow `wss://` connections on port 443, or use the SSE route instead |
| HTTP proxy does not support WebSocket upgrade | The `101 Switching Protocols` upgrade fails | Configure the proxy to allow WebSocket upgrades, or use the SSE route |
| Antivirus/security software | Works on a different machine | Add the platform's domains to the antivirus exception list |

**If the SSE stream is blocked:**
- The workspace falls back to polling job status, so updates arrive more slowly.
- Symptoms: job status only changes after a delay or a reload. Allowlist long-lived HTTPS responses from `www.ivybiosciences.com` (see the proxy table below).

## SSE streaming interrupted

Network conditions can interrupt the SSE streams used for chat and job events.

**Symptoms:**
- Chat response stops mid-sentence and resumes after a pause.
- A job's status jumps straight from a queued state to a finished one, skipping the intermediate updates.
- Browser console shows `EventSource` errors.

**Reconnection behavior:**
- The job event stream sends a heartbeat about every 15 seconds and closes after about 5 minutes, and the client then opens a new one.
- A new stream doesn't replay the events you missed. The client reads the job's current state instead, so the final status is still correct.

**Reducing interruptions:**
- Avoid switching networks (Wi-Fi to cellular, VPN connect/disconnect) while a response is streaming.
- If on a laptop, prevent sleep during long-running operations.
- Close bandwidth-intensive applications (video calls, large downloads) that compete for the connection.

## Corporate proxy setup

Many corporate networks route all traffic through an HTTP proxy. The platform works through most proxies, but some configurations cause issues.

**Proxy requirements for the platform:**

| Feature | Proxy requirement |
|---------|------------------|
| Basic browsing | Standard HTTPS pass-through |
| Authentication (Clerk) | Allow `clerk.ivybiosciences.com` and `accounts.ivybiosciences.com`, and their cookies |
| Scripts using the orchestrator WebSocket | Allow the `101 Switching Protocols` upgrade |
| Real-time updates in the workspace (SSE) | Allow long-lived HTTPS responses (the job stream stays open for up to about 5 minutes) |
| File uploads | Allow request bodies up to 100 MB (the per-file limit) and direct uploads to Amazon S3 |
| 3D viewer assets | Allow downloads from CDN domains |

**Self-signed certificates and TLS inspection:**
- Some corporate proxies inspect TLS by re-signing traffic with their own CA certificate ("SSL bumping" or "HTTPS interception").
- If your proxy does this, you may see certificate warnings or `ERR_CERT_AUTHORITY_INVALID` errors.
- Ask your IT team to either bypass TLS inspection for `*.ivybiosciences.com` or install the proxy's CA certificate in your browser's trust store.

**Proxy authentication:**
- If your proxy requires authentication, your browser should prompt for credentials.
- For scripts and the CLI, set the `HTTP_PROXY` and `HTTPS_PROXY` environment variables, with credentials if needed: `http://user:password@proxy.corp.example.com:8080`.

## VPN interference

VPN connections can interfere with the platform in several ways.

**Split tunneling:**
- With a full tunnel, all traffic, including the platform's, goes through the VPN's network. This adds latency and may add firewall restrictions.
- If split tunneling is available, route `*.ivybiosciences.com` traffic directly instead of through the VPN tunnel.

**DNS resolution through VPN:**
- Some VPNs override DNS resolution. If the VPN's DNS server can't resolve `ivybiosciences.com`, connections fail.
- Run `nslookup www.ivybiosciences.com` with and without the VPN connected. If the results differ or the VPN returns NXDOMAIN, the VPN's DNS is the issue.
- Ask your IT team to add `ivybiosciences.com` to the VPN's DNS configuration.

**MTU issues:**
- VPN tunnels reduce the effective MTU (Maximum Transmission Unit). If packets are too large, they may be dropped silently, which stalls connections.
- Symptoms: file uploads hang at a certain percentage, large API responses never complete.
- Fix: reduce the MTU on your local interface. On macOS: `sudo ifconfig en0 mtu 1400`. On Linux: `sudo ip link set dev eth0 mtu 1400`.

## API rate limits

The API applies a rate limit to each route class. When you exceed one, it returns HTTP `429 Too Many Requests`.

**Handling 429 responses:**
- The response includes a `Retry-After` header with the number of seconds to wait before retrying.
- Back off exponentially: wait `Retry-After` seconds, then twice that, then four times that if later attempts also receive `429`.
- Don't retry immediately in a tight loop.

Per-endpoint limits and header details are in [Rate limits](/docs/api/rate-limits) and [API & SDK issues](/docs/troubleshooting/api#429-rate-limited).

## Offline mode

The platform needs a network connection. Its service worker coordinates tabs and broadcasts online/offline status, but it doesn't cache pages or API responses.

**While you're offline:**
- A page that is already open keeps showing what it has loaded.
- You can't send chat messages, submit jobs, fetch new data, or sign in.
- Job status stops updating.

**Reconnection:**
- When you come back online, reload the page to resync chats and job status. Jobs keep running on the server while you're offline.

## CORS issues (self-hosting)

If you are self-hosting the platform, CORS (Cross-Origin Resource Sharing) errors are common during initial setup.

**Symptoms:**
- Browser console shows `Access-Control-Allow-Origin` errors.
- API calls from the frontend fail with "CORS policy" messages.
- Preflight OPTIONS requests return 403 or no CORS headers.

**Fixing CORS for self-hosting:**

1. **Next.js API routes.** The allowed origins are a fixed list in `src/middleware/helpers/corsHelpers.ts` and `src/middleware/handlers/routeHandlers.ts`. They are not read from an environment variable. Add your frontend origin to both lists and redeploy.
2. **Storage (Amazon S3).** Browser uploads go straight to the S3 bucket, so the bucket needs a CORS rule that allows `PUT` and `GET` from your frontend origin. The rule is generated from `src/config/s3Cors.ts` by `npm run build:s3-cors`.

## DNS resolution

If the platform is completely unreachable (not just slow), DNS resolution may be the issue.

**Diagnosis:**
- Run `nslookup www.ivybiosciences.com` or `dig www.ivybiosciences.com` from your terminal.
- If the lookup fails or returns a wrong IP, your DNS resolver may be misconfigured, blocked, or poisoned.

**Fixes:**
- Try a public DNS resolver: Google (`8.8.8.8`), Cloudflare (`1.1.1.1`), or Quad9 (`9.9.9.9`).
- If you are on a corporate network, ask IT whether `ivybiosciences.com` is blocked at the DNS level.
- Flush your local DNS cache: macOS: `sudo dscacheutil -flushcache`. Windows: `ipconfig /flushdns`. Linux: `sudo resolvectl flush-caches`.

**Custom domains (self-hosting):**
- If you run the platform on a custom domain, check that your DNS records (A, CNAME) point to the correct server.
- A record change reaches most resolvers within the old record's TTL, and can take up to 48 hours everywhere.

## Time skew

A wrong system clock can invalidate authentication tokens.

- Clerk session tokens carry `iat` (issued at) and `exp` (expires) timestamps and are short-lived. If your system clock is far off, tokens are rejected as expired or not yet valid.
- Sync your system time via NTP. On macOS: System Settings then General then Date & Time, enable "Set date and time automatically." On Linux: `sudo timedatectl set-ntp true`.
- If you can't sync time (air-gapped network), sign-in will keep failing. Contact support.

## Ticket checklist

If you need to contact support about a network issue:

- Endpoint URL and HTTP method
- Full response status code and body snippet (omit API keys and tokens)
- Timestamp, organization slug, and whether VPN or proxy was active
- Results of `nslookup www.ivybiosciences.com` from your machine
- Whether the issue reproduces on a different network (mobile hotspot)
- Browser DevTools Network tab export (HAR file) if possible