Connection refused

Cause: the ArmorIQ Proxy is not reachable.

Test connectivity

The SDK ships httpx, so use that rather than adding requests as an extra dependency just for this check.

import httpx

from armoriq_sdk import ArmorIQClient

client = ArmorIQClient()          # reads ARMORIQ_API_KEY
proxy_url = client.proxy_endpoint  # whatever your config actually resolved to

try:
    response = httpx.get(f"{proxy_url}/health", timeout=5.0)
    if response.status_code == 200:
        print(f"Proxy reachable at {proxy_url}")
    else:
        print(f"Proxy returned {response.status_code}")
except httpx.ConnectError:
    print("Cannot connect to proxy - check URL and network")
except httpx.TimeoutException:
    print("Connection timed out - check firewall")

Reading client.proxy_endpoint rather than hardcoding a URL matters: the endpoint is resolved from ARMORIQ_ENV, then any PROXY_ENDPOINT override, then the environment default. Hardcoding a host is the most common reason this check passes while the SDK still fails, or vice versa.

Common causes

Symptom	Likely cause
`ConnectError` on every call	Wrong endpoint for your environment, or egress blocked
Works locally, fails in CI	Runner has no outbound access to `*.armoriq.ai`
Works for the proxy but `get_intent_token` fails	IAP endpoint differs from the proxy; check both
`401` rather than a connection error	Reachable but the API key is rejected - not a connectivity problem

Check which endpoints the SDK resolved

from armoriq_sdk import ArmorIQClient

client = ArmorIQClient()
print("proxy:  ", client.proxy_endpoint)
print("backend:", client.backend_endpoint)
print("iap:    ", client.iap_endpoint)

Endpoint precedence, highest first:

explicit constructor arguments (proxy_endpoint=, iap_endpoint=, backend_endpoint=)
per-endpoint env vars: PROXY_ENDPOINT, IAP_ENDPOINT, BACKEND_ENDPOINT
use_production=False, which forces localhost regardless of ARMORIQ_ENV
ARMORIQ_ENV (production, staging, or local)
the environment baked into the installed package

Verified per environment with an ak_live_ key:

`ARMORIQ_ENV`	backend	proxy
`production`	`https://api.armoriq.ai`	`https://proxy.armoriq.ai`
`staging`	`https://staging-api.armoriq.ai`	`https://cloud-run-proxy.armoriq.io`
`local`	`http://127.0.0.1:3000`	`http://127.0.0.1:3001`

The IAP is https://iap.armoriq.ai, https://iap-staging.armoriq.ai, and http://127.0.0.1:8080 respectively.

On local, connection refused usually just means the services are not running. Check ports 3000 (backend), 3001 (proxy) and 8080 (IAP).

ak_claw_ keys ignore ARMORIQ_ENV. An ArmorClaw key resolves to the ArmorClaw endpoint family (*.armorclaw.io) and switches on use_production alone, because ArmorClaw has no staging row. So ARMORIQ_ENV=local with an ak_claw_ key still points at the remote ArmorClaw hosts, which is a confusing way to see connection errors. Pass use_production=False instead.

Configuration - env vars and armoriq.yaml
Error Handling - which exception each failure raises

Connection refused

Connection refused

Test connectivity

Common causes

Check which endpoints the SDK resolved

Related

On this page