{"record":{"id":"8321acddda6dacc8","repo":"usestrix/strix","slug":"postman-label-not-found-404-check-the-id-and","errorCode":null,"errorMessage":"Postman {label} not found (404). Check the id and that the key can access it.","messagePattern":"Postman (.+?) not found \\(404\\)\\. Check the id and that the key can access it\\.","errorType":"exception","errorClass":"SpecParseError","httpStatus":null,"severity":"error","filePath":"strix/utils/api_spec.py","lineNumber":261,"sourceCode":"    \"\"\"\n    if not api_key:\n        raise SpecParseError(\n            \"POSTMAN_API_KEY is not set. Export a Postman API key (PMAK-…) to \"\n            \"fetch from the Postman API, or pass a local collection file instead.\",\n        )\n    try:\n        response = requests.get(\n            url,\n            headers={\"X-Api-Key\": api_key, \"Accept\": \"application/json\"},\n            timeout=_POSTMAN_FETCH_TIMEOUT,\n        )\n    except requests.RequestException as exc:\n        raise SpecParseError(f\"Failed to reach the Postman API: {exc}\") from exc\n\n    if response.status_code == 401:\n        raise SpecParseError(\"Postman API rejected the key (401). Check POSTMAN_API_KEY.\")\n    if response.status_code == 404:\n        raise SpecParseError(\n            f\"Postman {label} not found (404). Check the id and that the key can access it.\",\n        )\n    if response.status_code != 200:\n        raise SpecParseError(f\"Postman API returned HTTP {response.status_code} for {label}.\")\n    try:\n        payload = response.json()\n    except ValueError as exc:\n        raise SpecParseError(f\"Postman API returned non-JSON for {label}\") from exc\n    if not isinstance(payload, dict):\n        raise SpecParseError(f\"Unexpected Postman API response shape for {label}\")\n    return payload\n\n\ndef fetch_postman_collection(collection_uid: str, api_key: str) -> dict[str, Any]:\n    \"\"\"Fetch a collection from the Postman API and return the raw collection dict.\n\n    Uses ``GET /collections/{uid}`` with the ``X-Api-Key`` header. The endpoint\n    wraps the collection under a ``collection`` key, unwrapped here so the result","sourceCodeStart":243,"sourceCodeEnd":279,"githubUrl":"https://github.com/usestrix/strix/blob/85513391305171ecc6faffe03da4a8bda5e3febb/strix/utils/api_spec.py#L243-L279","documentation":"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.","triggerScenarios":"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.","commonSituations":"Confusing the Postman collection ID shown in the URL with the API UID; team workspace permissions excluding the integration key; resource moved between workspaces.","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)"],"exampleFix":"# before\nstrix --api-spec postman:my-api-collection\n\n# after\nstrix --api-spec postman:12345678-abcd-ef01-2345-6789abcdef01","handlingStrategy":"validation","validationCode":"import re, requests, os\n\nUID_RE = re.compile(r\"^[0-9a-f-]{8,}\")\nassert UID_RE.match(collection_uid), \"use the collection UID, not its name\"\nr = requests.get(\"https://api.getpostman.com/collections\",\n                 headers={\"X-Api-Key\": os.environ[\"POSTMAN_API_KEY\"]}, timeout=10)\nknown = {c[\"uid\"] for c in r.json().get(\"collections\", [])}\nassert collection_uid in known, \"UID not visible to this key\"","typeGuard":null,"tryCatchPattern":"except SpecParseError as e:\n    if \"not found (404)\" in str(e):\n        re-enumerate collections and match by name to recover the correct UID; retry once","preventionTips":["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"],"tags":["postman","http-404","resource-not-found"],"backgroundTag":null,"analyzedSha":"85513391305171ecc6faffe03da4a8bda5e3febb","analyzedAt":"2026-08-15T05:03:57.275Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}