{"record":{"id":"79d9f86b3fcad26d","repo":"calesthio/OpenMontage","slug":"atlas-cloud-returned-an-unexpected-payload-str-b","errorCode":null,"errorMessage":"Atlas Cloud returned an unexpected payload: {str(body)[:500]}","messagePattern":"Atlas Cloud returned an unexpected payload: (.+?)","errorType":"exception","errorClass":"AtlasError","httpStatus":null,"severity":"error","filePath":"tools/atlas_client.py","lineNumber":82,"sourceCode":"    if json_body:\n        headers[\"Content-Type\"] = \"application/json\"\n    return headers\n\n\ndef _payload_of(response: Any) -> dict[str, Any]:\n    \"\"\"Parse an Atlas envelope, raising AtlasError with the body on any problem.\n\n    Atlas wraps results as {\"code\": 200, \"data\": {...}}. A non-200 `code` can ride\n    along with HTTP 200, so the envelope is checked even on a successful request.\n    \"\"\"\n    try:\n        body = response.json()\n    except Exception as exc:  # noqa: BLE001 - surface the raw text, not a parse trace\n        text = getattr(response, \"text\", \"\")\n        raise AtlasError(f\"Atlas Cloud returned a non-JSON response: {text[:500]}\") from exc\n\n    if not isinstance(body, dict):\n        raise AtlasError(f\"Atlas Cloud returned an unexpected payload: {str(body)[:500]}\")\n\n    code = body.get(\"code\")\n    if code is not None and int(code) != 200:\n        message = body.get(\"message\") or body.get(\"error\") or str(body)[:500]\n        raise AtlasError(f\"Atlas Cloud error (code {code}): {message}\")\n\n    data = body.get(\"data\")\n    if data is None:\n        # uploadMedia historically answered with a bare {\"url\": ...}.\n        return body\n    if not isinstance(data, dict):\n        raise AtlasError(f\"Atlas Cloud returned an unexpected 'data' field: {str(data)[:500]}\")\n    return data\n\n\ndef _raise_for_status(response: Any, context: str) -> None:\n    status = getattr(response, \"status_code\", 200)\n    if status >= 400:","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/calesthio/OpenMontage/blob/95e1c3d0ab93482159818560f6a8c8e866b9139f/tools/atlas_client.py#L64-L100","documentation":"Raised by _payload_of when the Atlas response parses as JSON but the top-level value is not an object (e.g. a JSON array, string, or number). The Atlas envelope contract is {\"code\": ..., \"data\": ...}, so any other top-level shape is treated as a protocol violation and the first 500 chars are included for diagnosis.","triggerScenarios":"A poll or submit response whose body is a bare JSON array of predictions; a string or numeric body returned by a misrouted endpoint or an API version change; server bugs emitting an unenveloped payload.","commonSituations":"Atlas API contract drift after an upgrade; hitting a listing endpoint instead of the prediction endpoint due to URL construction bugs; debugging proxies returning JSON-encoded metadata arrays.","solutions":["Log the included body snippet and compare against the expected {\"code\":200,\"data\":{...}} envelope","Confirm the endpoint URL being passed (endpoint argument typos often land on collection endpoints that return arrays)","Check for Atlas API changelog updates that altered the envelope","If the body is actually a valid alternate shape used by a legacy endpoint (like bare {\"url\":...}), note that _payload_of only allows dict — update the client or the endpoint used"],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":"def is_atlas_envelope(body: object) -> bool:\n    return isinstance(body, dict) and (\"code\" in body or \"data\" in body or \"url\" in body)","tryCatchPattern":"try:\n    data = _payload_of(resp)\nexcept AtlasError as e:\n    if \"unexpected payload\" in str(e):\n        logger.error(\"Atlas contract drift; body=%r\", resp.text[:500])\n    raise","preventionTips":["Pin the Atlas API version your client targets","Add integration tests asserting the envelope shape so drift is caught in CI","Double-check endpoint URLs — collection endpoints return arrays"],"tags":["atlas-cloud","json","api-contract","validation"],"backgroundTag":null,"analyzedSha":"95e1c3d0ab93482159818560f6a8c8e866b9139f","analyzedAt":"2026-08-15T06:31:20.014Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}