Skip to content
New Listings Feed

Loading…

    v2 WebSocketLimits and errors

    Limits and errors

    Request limits, HTTP errors, and retry handling.

    Open connections

    Each key can open up to three simultaneous connections per public IP, per region, and per v2 endpoint. Full and Fast have separate connection and active-IP counts.

    Key Included IPs Total connections
    FREE 2 6
    STARTER 1 3
    PRO 1 3

    The totals above are for one endpoint in one region. FREE has Full access only. A paid key using one IP can open three Full and three Fast connections in each of Tokyo, New York and Seoul.

    Connections using the same key and public IP share the three slots for that endpoint and region, even with different filters or applications. Different keys have separate slots.

    Additional IPs increase the total to 3 × ip_limit per endpoint and region. See Keys for additional-IP terms. The READY message reports your current allowance as subscription.ip_limit; subscription.active_ips counts IP addresses, not connections.

    Exceeding either the IP allowance or the three-connection limit produces CONNECTION_LIMIT_REACHED followed by WebSocket close code 1008. Close an existing connection before retrying.

    ws.newlistings.pro and tokyo.newlistings.pro share Tokyo Full's connection, active-IP, and request limits. Switching between these hostnames does not add capacity.

    Connection and history requests

    Each serving endpoint applies these budgets separately. They are not one shared total across all endpoints and regions. On Full, HTTPS history requests and WebSocket connection attempts share the same budgets.

    History requests use no WebSocket connection or IP slots. You can query history while all those slots are occupied.

    Limit Budget
    Attempts per IP 120 per 60 seconds
    Attempts per key 30 per 60 seconds

    When a limit is reached, the request returns HTTP 429 with error code RATE_LIMITED. Wait at least the number of seconds in the Retry-After header before trying again, even if it exceeds your usual reconnect backoff cap. Repeatedly reconnecting or querying history does not bypass these limits.

    Repeated attempts with an inactive or expired key can trigger longer cooldowns. Fix the key before reconnecting.

    Request errors

    Failed WebSocket upgrades return HTTP responses before a socket opens. These errors also apply to Full history requests; the history-specific codes are marked below.

    HTTP status Code What to do
    400 INVALID_REQUEST Correct the URL, filters, host, or headers before retrying.
    401 AUTHENTICATION_FAILED Check the key and endpoint. A new key may need a short activation delay.
    401 KEY_EXPIRED Renew the key before reconnecting.
    403 HISTORY_NOT_INCLUDED History requires a STARTER or PRO key.
    429 RATE_LIMITED Wait for Retry-After before retrying.
    503 HISTORY_UNAVAILABLE The history query failed. Retry with backoff.

    Upgrade errors use {"type":"error","code":"...","message":"..."}. History validation, plan, and storage errors use {"error":"..."}; authentication and rate-limit errors use the upgrade format.

    A missing or invalid key and an unavailable authentication service can share AUTHENTICATION_FAILED. If a working key starts failing, check service status before repeatedly retrying.

    For errors after the socket opens, see Connection lifecycle.