usestrix/strix · error · SpecParseError

Postman {label} not found (404). Check the id and that the k

Error message

Postman {label} not found (404). Check the id and that the key can access it.

What it means

SpecParseError raised when the Postman API answers HTTP 404 for the requested resource (label identifies it, e.g. 'collection 12345-abc'). The key is valid but no such collection/environment UID is visible to it — wrong id, deleted resource, or the key lacks workspace access.

Source

Thrown at strix/utils/api_spec.py:261

    """
    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


def fetch_postman_collection(collection_uid: str, api_key: str) -> dict[str, Any]:
    """Fetch a collection from the Postman API and return the raw collection dict.

    Uses ``GET /collections/{uid}`` with the ``X-Api-Key`` header. The endpoint
    wraps the collection under a ``collection`` key, unwrapped here so the result

View on GitHub (pinned to 8551339130)

Solutions

Get the correct UID: curl -H "X-Api-Key: $POSTMAN_API_KEY" https://api.getpostman.com/collections
Confirm the collection still exists and lives in a workspace the key can access
Check you passed a collection UID (not a name or environment UID)

Example fix

# before
strix --api-spec postman:my-api-collection

# after
strix --api-spec postman:12345678-abcd-ef01-2345-6789abcdef01

Defensive patterns

Strategy: validation

Validate before calling

import re, requests, os

UID_RE = re.compile(r"^[0-9a-f-]{8,}")
assert UID_RE.match(collection_uid), "use the collection UID, not its name"
r = requests.get("https://api.getpostman.com/collections",
                 headers={"X-Api-Key": os.environ["POSTMAN_API_KEY"]}, timeout=10)
known = {c["uid"] for c in r.json().get("collections", [])}
assert collection_uid in known, "UID not visible to this key"

Try / catch

except SpecParseError as e:
    if "not found (404)" in str(e):
        re-enumerate collections and match by name to recover the correct UID; retry once

Prevention

Look up UIDs via GET /collections instead of copying from URLs
Store UIDs in config, not free-typed CLI arguments
Confirm the key has access to the collection's workspace

When it happens

Trigger: Typing the collection UID; using the collection name instead of the UID (format: uuid-uuid); the collection was deleted or moved to a workspace the key cannot see; copying an environment UID where a collection UID was expected.

Common situations: Confusing the Postman collection ID shown in the URL with the API UID; team workspace permissions excluding the integration key; resource moved between workspaces.

Related errors

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