Connection Issues

Connection drops are normal for HTTP/REST APIs. Various infrastructure layers (load balancers, proxies, firewalls) have timeout limits. All API clients must implement automatic reconnection logic with exponential backoff - this is not optional.

Required Client Implementation

All API clients must implement:

Automatic reconnection for both REST and gRPC when connections drop
Retry logic with exponential backoff for transient connection errors
Keepalive configuration for gRPC streams (60s interval recommended)
Timeout detection (15s for REST, 180s for stream silence)
Connection pooling with stale connection detection for REST
Traffic activity - don’t leave connections idle for 10+ minutes

ALB 10-Minute Timeout

SocketError: “other side closed” every 10 minutes

Cause: Application Load Balancer (ALB) timeout, set to 10 minutes by design. If your connection has no activity for 10 minutes, the ALB will close it. Solution: Implement automatic reconnection logic in your client. If you’re not sending traffic for 10 minutes, your code should handle reconnect gracefully. Note: The 10-minute timeout is intentional and will not be increased. Proper client implementation (connection pooling, keepalives, reconnection) is the correct solution.

gRPC Connection Issues

14 UNAVAILABLE Errors

gRPC streams can drop with “14 UNAVAILABLE” errors for two reasons: (a) 10-minute ALB timeout: If you create a gRPC channel but don’t open a stream immediately, or if there’s no actual traffic on the stream for 10 minutes, the ALB will timeout the connection. (b) Keepalives alone may not prevent timeout: The ALB needs to see actual traffic, not just HTTP/2 PING frames. Solutions:

Implement automatic reconnection when streams drop (error code 14 or EOF)
Open streams promptly after creating channels
If you have long idle periods, consider periodic lightweight API calls to keep the connection active

Recommended gRPC Keepalive Settings

# Python example
import grpc

channel = grpc.secure_channel(
    'grpc-preprod.polymarketexchange.com:443',
    grpc.ssl_channel_credentials(),
    options=[
        ('grpc.keepalive_time_ms', 60000),           # Send keepalive every 60s
        ('grpc.keepalive_timeout_ms', 20000),        # Wait 20s for keepalive response
        ('grpc.keepalive_permit_without_calls', 1),  # Send keepalives when idle
    ]
)

// Node.js example
const grpc = require('@grpc/grpc-js');

const channel = new grpc.ChannelCredentials.createSsl();
const client = new YourServiceClient(
  'grpc-preprod.polymarketexchange.com:443',
  channel,
  {
    'grpc.keepalive_time_ms': 60000,
    'grpc.keepalive_timeout_ms': 20000,
    'grpc.keepalive_permit_without_calls': 1
  }
);

Note: Keepalives help detect broken connections, but they may not prevent ALB timeouts if there’s no actual API traffic for 10+ minutes.

Stream Goes Dark (No Heartbeat for >180 Seconds)

Cause: Connections being severed on the hosts. Recent infrastructure fixes should have resolved this issue. Solution: Implement 180-second timeout detection on your end. Trigger automatic reconnection when no data received for 180+ seconds. This error should be rare after recent stability improvements.

REST Connection Errors

ECONNRESET, EPIPE, “other side closed”

Cause: Transient network issues, stale connections, or load balancer timeouts. Solution: Implement exponential backoff with 2-3 retries for connection errors:

import time
import requests
from requests.exceptions import ConnectionError

def make_request_with_retry(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        try:
            return requests.post(url, headers=headers, json=data, timeout=15)
        except ConnectionError as e:
            if attempt == max_retries - 1:
                raise
            wait_time = 2 ** attempt  # 1s, 2s, 4s
            time.sleep(wait_time)

Stale Connection Handling

Configure your HTTP client’s connection pool to detect and remove closed connections before reuse:

# Python with requests
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

session = requests.Session()
retry = Retry(
    total=3,
    backoff_factor=1,
    status_forcelist=[502, 503, 504],
    allowed_methods=["GET", "POST"]
)
adapter = HTTPAdapter(max_retries=retry, pool_connections=10, pool_maxsize=20)
session.mount('https://', adapter)

// Node.js with Undici
const { Pool } = require('undici');

const pool = new Pool('https://api.preprod.polymarketexchange.com', {
  connections: 10,
  pipelining: 1,
  keepAliveTimeout: 60000,
  keepAliveMaxTimeout: 600000
});

Request Timeouts

Recommendation: Add 15-second timeouts on client side to prevent hanging requests. A small percentage of calls may never resolve - timeout protection is essential.

# Python
response = requests.post(url, json=data, timeout=15)

// Node.js with fetch
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 15000);

const response = await fetch(url, {
  signal: controller.signal,
  headers: headers,
  body: JSON.stringify(data)
});
clearTimeout(timeoutId);

Connection Best Practices

Use Batch Endpoints

Batch endpoints reduce overall connection load significantly:

/v1/trading/orders/list - Retrieve multiple orders at once
/v1/trading/orders/cancel/list - Cancel multiple orders in one call

Implement Connection Pooling

Reuse connections across requests
Configure appropriate pool sizes for your traffic patterns
Ensure stale connections are detected and recycled

Avoid Creating Idle Connections

Don’t create gRPC channels or HTTP connections unless you’re actively using them
If you need to maintain a connection, ensure regular traffic (not just keepalives)

Timeout / No Response

If requests hang without returning a response:

Step 1: Verify Your Token

Ensure your access token is valid and not expired:

import base64
import json

# Decode the payload (middle part of JWT)
payload = access_token.split('.')[1]
payload += '=' * (4 - len(payload) % 4)  # Add padding
claims = json.loads(base64.urlsafe_b64decode(payload))

print("Token expires:", claims.get("exp"))
print("Granted scopes:", claims.get("scope", ""))

Step 2: Check Endpoint URL

Ensure you’re using the correct API base URL for your environment:

Environment	API Base URL
Pre-production	`https://api.preprod.polymarketexchange.com`
Production	`https://api.prod.polymarketexchange.com`

Step 3: Verify Network Connectivity

Test basic connectivity to the API:

curl -I https://api.preprod.polymarketexchange.com/v1/health

Expected response: {"status":"ok"} with HTTP 200.

Error 464

When receiving a 464 error in prod or pre-prod environments, verify that the Host header is set correctly:

Host: api.preprod.polymarketexchange.com

Host: api.prod.polymarketexchange.com

Without the correct host header, requests may be routed incorrectly.

Connection Reset / Connection Refused

This indicates network-level issues before reaching the API: Possible causes:

DNS resolution failure - Check that api.{env}.polymarketexchange.com resolves correctly
TLS handshake failure - Your client may not support required TLS version (TLS 1.2+)
Firewall blocking - Your network may block outbound HTTPS
IP address blocked - Your IP may be blocked for suspicious activity

Test connectivity:

curl -v https://api.{env}.polymarketexchange.com/v1/health

The -v flag shows connection details to help identify where the failure occurs.

Curl Command Issues

Drops to Blinking Cursor

If your curl command drops to a new line with a blinking cursor, this indicates a formatting issue with the command itself, not a connection problem. Common causes:

Missing quotation marks
Missing escape characters
Malformed command syntax

Example of correct curl formatting:

curl -X POST https://api.preprod.polymarketexchange.com/v1/trading/orders \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instrument": "tec-nfl-sbw-2026-02-08-kc",
    "side": "buy",
    "quantity": 100
  }'

Platform-Specific Issues

Windows and Python HTTP/2

Windows instances and Python applications may encounter HTTP/2 compatibility issues: Windows: Ensure HTTP/2 is enabled in your system settings. Python: Use the httpx library instead of requests:

import httpx

# Use httpx for HTTP/2 support
with httpx.Client(http2=True) as client:
    response = client.get(
        "https://api.preprod.polymarketexchange.com/v1/health",
        headers={"Authorization": f"Bearer {token}"}
    )

HTTP/2 vs HTTP/1.1

Both protocols are supported:

HTTP/2: Better performance for multiple concurrent requests
HTTP/1.1: Works fine for most use cases

If you encounter issues with HTTP/2, you can force HTTP/1.1 in most HTTP clients.

SSL/TLS Issues

Certificate Verification Failures

If you receive SSL certificate verification errors: In production code: Never disable certificate verification. This creates security vulnerabilities. For debugging only: You can temporarily disable verification to test connectivity:

# DEBUGGING ONLY - DO NOT USE IN PRODUCTION
import requests
response = requests.get(url, verify=False)

Proper solution: Ensure your system has up-to-date CA certificates installed.

Proxy and Firewall

Behind a Corporate Proxy

If you’re behind a corporate proxy:

# Set proxy environment variables
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# Or in Python
proxies = {
    'http': 'http://proxy.example.com:8080',
    'https': 'http://proxy.example.com:8080',
}
response = requests.get(url, proxies=proxies)

Firewall Restrictions

Ensure your firewall allows outbound HTTPS connections to:

*.polymarketexchange.com on port 443
*.auth0.com on port 443 (for authentication)

DNS Issues

Cannot Resolve Hostname

Test DNS resolution:

nslookup api.preprod.polymarketexchange.com
# or
dig api.preprod.polymarketexchange.com

If DNS fails, check:

Your DNS server configuration
Whether you can resolve other domains
Whether there’s a local hosts file override

Health Check Endpoint

Use the health check endpoint to verify API availability:

curl https://api.{env}.polymarketexchange.com/v1/health

Expected response: {"status":"ok"} with HTTP 200 No authentication required - this endpoint is publicly accessible. If the health check fails, the API may be experiencing issues. Check the status page or contact support.

Trader Guide

Getting Started

Configuration

Guides

Required Client Implementation

ALB 10-Minute Timeout

SocketError: “other side closed” every 10 minutes

gRPC Connection Issues

14 UNAVAILABLE Errors

Recommended gRPC Keepalive Settings

Stream Goes Dark (No Heartbeat for >180 Seconds)

REST Connection Errors

ECONNRESET, EPIPE, “other side closed”

Stale Connection Handling

Request Timeouts

Connection Best Practices

Use Batch Endpoints

Implement Connection Pooling

Avoid Creating Idle Connections

Timeout / No Response

Step 1: Verify Your Token

Step 2: Check Endpoint URL

Step 3: Verify Network Connectivity

Error 464

Connection Reset / Connection Refused

Curl Command Issues

Drops to Blinking Cursor

Platform-Specific Issues

Windows and Python HTTP/2

HTTP/2 vs HTTP/1.1

SSL/TLS Issues

Certificate Verification Failures

Proxy and Firewall

Behind a Corporate Proxy

Firewall Restrictions

DNS Issues

Cannot Resolve Hostname

Health Check Endpoint

​Required Client Implementation

​ALB 10-Minute Timeout

​SocketError: “other side closed” every 10 minutes

​gRPC Connection Issues

​14 UNAVAILABLE Errors

​Recommended gRPC Keepalive Settings

​Stream Goes Dark (No Heartbeat for >180 Seconds)

​REST Connection Errors

​ECONNRESET, EPIPE, “other side closed”

​Stale Connection Handling

​Request Timeouts

​Connection Best Practices

​Use Batch Endpoints

​Implement Connection Pooling

​Avoid Creating Idle Connections

​Timeout / No Response

​Step 1: Verify Your Token

​Step 2: Check Endpoint URL

​Step 3: Verify Network Connectivity

​Error 464

​Connection Reset / Connection Refused

​Curl Command Issues

​Drops to Blinking Cursor

​Platform-Specific Issues

​Windows and Python HTTP/2

​HTTP/2 vs HTTP/1.1

​SSL/TLS Issues

​Certificate Verification Failures

​Proxy and Firewall

​Behind a Corporate Proxy

​Firewall Restrictions

​DNS Issues

​Cannot Resolve Hostname

​Health Check Endpoint

Required Client Implementation

ALB 10-Minute Timeout

SocketError: “other side closed” every 10 minutes

gRPC Connection Issues

14 UNAVAILABLE Errors

Recommended gRPC Keepalive Settings

Stream Goes Dark (No Heartbeat for >180 Seconds)

REST Connection Errors

ECONNRESET, EPIPE, “other side closed”

Stale Connection Handling

Request Timeouts

Connection Best Practices

Use Batch Endpoints

Implement Connection Pooling

Avoid Creating Idle Connections

Timeout / No Response

Step 1: Verify Your Token

Step 2: Check Endpoint URL

Step 3: Verify Network Connectivity

Error 464

Connection Reset / Connection Refused

Curl Command Issues

Drops to Blinking Cursor

Platform-Specific Issues

Windows and Python HTTP/2

HTTP/2 vs HTTP/1.1

SSL/TLS Issues

Certificate Verification Failures

Proxy and Firewall

Behind a Corporate Proxy

Firewall Restrictions

DNS Issues

Cannot Resolve Hostname

Health Check Endpoint