calesthio/OpenMontage · error · AtlasError

Atlas Cloud returned an unexpected payload: {str(body)[:500]

Error message

Atlas Cloud returned an unexpected payload: {str(body)[:500]}

What it means

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.

Source

Thrown at tools/atlas_client.py:82

    if json_body:
        headers["Content-Type"] = "application/json"
    return headers


def _payload_of(response: Any) -> dict[str, Any]:
    """Parse an Atlas envelope, raising AtlasError with the body on any problem.

    Atlas wraps results as {"code": 200, "data": {...}}. A non-200 `code` can ride
    along with HTTP 200, so the envelope is checked even on a successful request.
    """
    try:
        body = response.json()
    except Exception as exc:  # noqa: BLE001 - surface the raw text, not a parse trace
        text = getattr(response, "text", "")
        raise AtlasError(f"Atlas Cloud returned a non-JSON response: {text[:500]}") from exc

    if not isinstance(body, dict):
        raise AtlasError(f"Atlas Cloud returned an unexpected payload: {str(body)[:500]}")

    code = body.get("code")
    if code is not None and int(code) != 200:
        message = body.get("message") or body.get("error") or str(body)[:500]
        raise AtlasError(f"Atlas Cloud error (code {code}): {message}")

    data = body.get("data")
    if data is None:
        # uploadMedia historically answered with a bare {"url": ...}.
        return body
    if not isinstance(data, dict):
        raise AtlasError(f"Atlas Cloud returned an unexpected 'data' field: {str(data)[:500]}")
    return data


def _raise_for_status(response: Any, context: str) -> None:
    status = getattr(response, "status_code", 200)
    if status >= 400:

View on GitHub (pinned to 95e1c3d0ab)

Solutions

1. Log the included body snippet and compare against the expected {"code":200,"data":{...}} envelope
2. Confirm the endpoint URL being passed (endpoint argument typos often land on collection endpoints that return arrays)
3. Check for Atlas API changelog updates that altered the envelope
4. 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

def is_atlas_envelope(body: object) -> bool:
    return isinstance(body, dict) and ("code" in body or "data" in body or "url" in body)

try:
    data = _payload_of(resp)
except AtlasError as e:
    if "unexpected payload" in str(e):
        logger.error("Atlas contract drift; body=%r", resp.text[:500])
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Atlas Cloud returned an unexpected 'data' field: {str(data)[
• Atlas Cloud did not return a prediction id: {str(data)[:500]
• Atlas Cloud upload returned no URL: {str(data)[:500]}
• Atlas Cloud returned a non-JSON response: {text[:500]}
• Prediction {prediction_id} reported '{last_status}' but retu

AI-assisted analysis of calesthio/OpenMontage@95e1c3d0ab (2026-08-15). Data as JSON: /api/errors/79d9f86b3fcad26d. Report an issue: GitHub.