calesthio/OpenMontage · error · AtlasError

Atlas Cloud returned a non-JSON response: {text[:500]}

Error message

Atlas Cloud returned a non-JSON response: {text[:500]}

What it means

Raised by _payload_of when response.json() fails while parsing an Atlas Cloud response, meaning the server returned a body that is not valid JSON (typically HTML or empty). The first 500 characters of the raw body are included to expose what actually came back. This guards every Atlas call: submit, poll, and upload_media all route through _payload_of.

Source

Thrown at tools/atlas_client.py:79

def _headers(api_key: str, json_body: bool = True) -> dict[str, str]:
    headers = {"Authorization": f"Bearer {api_key}"}
    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

View on GitHub (pinned to 95e1c3d0ab)

Solutions

  1. Inspect the included body snippet — HTML title usually names the culprit (proxy, WAF, outage page)
  2. Retry after a short delay; transient gateway HTML responses typically resolve
  3. If persistent, verify the Atlas endpoint URL and network path (proxy bypass) for the API host
  4. Check Atlas Cloud status page for incidents

Example fix

// before
pred_id = atlas_client.submit(endpoint, payload, api_key)

// after — retry transient parse failures
for attempt in range(3):
    try:
        pred_id = atlas_client.submit(endpoint, payload, api_key)
        break
    except AtlasError as e:
        if "non-JSON" not in str(e) or attempt == 2:
            raise
        time.sleep(5 * (attempt + 1))
Defensive patterns

Strategy: retry

Try / catch

try:
    data = atlas_client.submit(endpoint, payload, api_key)
except AtlasError as e:
    if "non-JSON" not in str(e):
        raise
    time.sleep(5)
    data = atlas_client.submit(endpoint, payload, api_key)  # single retry

Prevention

When it happens

Trigger: Any submit/poll/upload request whose response is an HTML error page from a gateway (502/503), a WAF challenge, or an empty body from a dropped connection; DNS pointing at the wrong host serving a landing page.

Common situations: Atlas Cloud transient gateway outages; corporate proxies injecting HTML; wrong ATLASCLOUD base endpoint URL from a stale env var; response bodies truncated by intermediary timeouts.

Related errors

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