usestrix/strix · error · SpecParseError

Failed to reach the Postman API: {exc}

Error message

Failed to reach the Postman API: {exc}

What it means

SpecParseError raised when requests.get to api.getpostman.com raises RequestException — DNS failure, connection refused, TLS error, or the 30-second timeout (_POSTMAN_FETCH_TIMEOUT). The original exception is chained for detail.

Source

Thrown at strix/utils/api_spec.py:256

def _postman_api_json(url: str, api_key: str, label: str) -> dict[str, Any]:
    """GET a Postman API resource and return the parsed JSON payload.

    Raises :class:`SpecParseError` with an actionable message on auth, network,
    or shape errors.
    """
    if not api_key:
        raise SpecParseError(
            "POSTMAN_API_KEY is not set. Export a Postman API key (PMAK-…) to "
            "fetch from the Postman API, or pass a local collection file instead.",
        )
    try:
        response = requests.get(
            url,
            headers={"X-Api-Key": api_key, "Accept": "application/json"},
            timeout=_POSTMAN_FETCH_TIMEOUT,
        )
    except requests.RequestException as exc:
        raise SpecParseError(f"Failed to reach the Postman API: {exc}") from exc

    if response.status_code == 401:
        raise SpecParseError("Postman API rejected the key (401). Check POSTMAN_API_KEY.")
    if response.status_code == 404:
        raise SpecParseError(
            f"Postman {label} not found (404). Check the id and that the key can access it.",
        )
    if response.status_code != 200:
        raise SpecParseError(f"Postman API returned HTTP {response.status_code} for {label}.")
    try:
        payload = response.json()
    except ValueError as exc:
        raise SpecParseError(f"Postman API returned non-JSON for {label}") from exc
    if not isinstance(payload, dict):
        raise SpecParseError(f"Unexpected Postman API response shape for {label}")
    return payload

View on GitHub (pinned to 8551339130)

Solutions

  1. Verify connectivity: curl -sS https://api.getpostman.com -o /dev/null -w '%{http_code}'
  2. Set HTTPS_PROXY/HTTP_PROXY if a corporate proxy is required
  3. If egress is blocked, export the collection as a local JSON file and pass that instead

Example fix

# before: sandboxed CI with no egress
strix --api-spec postman:12345-abcdef

# after: export locally, ship the file
curl -H "X-Api-Key: $POSTMAN_API_KEY" https://api.getpostman.com/collections/12345-abcdef | jq .collection > coll.json
strix --api-spec ./coll.json
Defensive patterns

Strategy: retry

Validate before calling

import socket, os

def postman_reachable(timeout: float = 5) -> bool:
    if os.environ.get("HTTPS_PROXY"):
        return True  # assume proxy handles egress
    try:
        socket.create_connection(("api.getpostman.com", 443), timeout=timeout).close()
        return True
    except OSError:
        return False

Try / catch

try:
    payload = _postman_api_json(url, key, label)
except SpecParseError as e:
    if "Failed to reach" in str(e) and is_transient(e.__cause__):
        sleep with backoff once, then fall back to a local export on second failure

Prevention

When it happens

Trigger: Running in an air-gapped or proxied network where api.getpostman.com is unreachable; corporate TLS interception with an untrusted CA; slow networks exceeding the 30s timeout.

Common situations: CI runner without internet egress; Docker sandbox with blocked outbound traffic; missing HTTPS_PROXY setting behind a corporate proxy.

Related errors

AI-assisted analysis of usestrix/strix@8551339130 (2026-08-15). Data as JSON: /api/errors/f2c49680f9c3e90b. Report an issue: GitHub.