{"record":{"id":"a092030f97851228","repo":"calesthio/OpenMontage","slug":"atlas-cloud-error-code-code-message","errorCode":null,"errorMessage":"Atlas Cloud error (code {code}): {message}","messagePattern":"Atlas Cloud error \\(code (.+?)\\): (.+?)","errorType":"exception","errorClass":"AtlasError","httpStatus":null,"severity":"error","filePath":"tools/atlas_client.py","lineNumber":87,"sourceCode":"def _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:\n        text = getattr(response, \"text\", \"\")\n        raise AtlasError(f\"{context} failed with HTTP {status}: {text[:500]}\")\n\n\ndef submit(endpoint: str, payload: dict[str, Any], api_key: str, timeout: int = 60) -> str:","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/calesthio/OpenMontage/blob/95e1c3d0ab93482159818560f6a8c8e866b9139f/tools/atlas_client.py#L69-L105","documentation":"Raised by _payload_of when the Atlas envelope's application-level code field is present and not 200 — even when the HTTP status itself is 200. Atlas reports business errors (auth, insufficient credits, invalid model, parameter rejection) inside the envelope, so this check is what actually surfaces them. The message prefers body.message, then body.error, then a truncated dump.","triggerScenarios":"Submitting a generation with an invalid/expired API key (envelope code for unauthorized); insufficient credits or plan restrictions on a premium model; invalid payload fields (bad aspect_ratio, unknown model slug); a poll response where the platform wrapped an error with HTTP 200.","commonSituations":"Rotated API key not refreshed in env; free-tier credit exhaustion mid-render; typos in model endpoint slugs; region-locked models requested from an unsupported account.","solutions":["Read the embedded message — auth codes mean refresh the Atlas API key, credit codes mean top up the account","Log the full response body (minus auth headers) at the call site for the exact rejection reason","Validate payload fields (model slug, aspect ratio, duration) against current Atlas docs before submitting","For credit/auth issues, add a preflight balance or key check if the API offers one"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    data = _payload_of(resp)\nexcept AtlasError as e:\n    msg = str(e)\n    if \"Atlas Cloud error (code\" in msg:\n        # business rejection — inspect code, do NOT blind-retry\n        logger.error(\"Atlas rejected request: %s\", msg)\n        raise\n    raise","preventionTips":["Never blind-retry envelope errors — most are auth/credit/parameter rejections that repeat","Keep the API key in a secret manager and refresh it atomically","Validate payload fields against current docs before submitting"],"tags":["atlas-cloud","api","auth","billing","envelope"],"backgroundTag":null,"analyzedSha":"95e1c3d0ab93482159818560f6a8c8e866b9139f","analyzedAt":"2026-08-15T06:31:20.014Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}