TencentCloud/TencentDB-Agent-Memory · error · TDAMError

-1

-1

Error message

API response must be a JSON object

What it means

_decode_response raises TDAMError with code -1 and 'API response must be a JSON object' when the body parses as JSON but is not a dict (e.g. a JSON array, string, number, or null). The SDK requires the envelope contract (a JSON object with code/data fields) to proceed.

Source

Thrown at sdk/memory-core/python/tencentdb_agent_memory/_v3_http.py:51

        raise ParamError("service_id must be provided")
    if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or timeout <= 0:
        raise ParamError("timeout must be a positive number")


def _decode_response(resp: httpx.Response) -> dict:
    header_request_id = (
        resp.headers.get("x-qcloud-transaction-id")
        or resp.headers.get("x-trace-id")
        or ""
    )
    try:
        envelope = resp.json()
    except ValueError as exc:
        message = resp.text or f"HTTP {resp.status_code} returned a non-JSON response"
        raise TDAMError(resp.status_code if resp.is_error else -1, message, header_request_id) from exc

    if not isinstance(envelope, dict):
        raise TDAMError(-1, "API response must be a JSON object", header_request_id)

    code = envelope.get("code")
    if resp.is_error or code != 0:
        effective_code = code if isinstance(code, int) and code != 0 else resp.status_code
        payload = envelope.get("data")
        details = payload if isinstance(payload, dict) else None
        raise TDAMError(
            code=effective_code,
            message=str(envelope.get("message") or f"HTTP {resp.status_code}"),
            request_id=str(envelope.get("request_id") or header_request_id),
            details=details,
        )

    result = envelope.get("data") or {}
    if not isinstance(result, dict):
        raise TDAMError(-1, "API response data must be a JSON object", header_request_id)
    trace_id = resp.headers.get("x-trace-id")
    if trace_id:

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Confirm the endpoint returns the documented envelope object {"code":..., "data":...}
2. Check base_url/path configuration for stub, mock, or outdated gateway URLs
3. Capture the raw response (curl the same URL) to see the actual JSON type being returned
4. Upgrade/downgrade the SDK to match the server's envelope contract version

Example fix

# before
client = TDAMClient(base_url="http://localhost:9000/mock")  # mock returns []
# after
client = TDAMClient(base_url="https://api.example.com/v3")  # returns {"code":0,"data":{...}}

# preflight: confirm the endpoint returns an object envelope
import requests, json
r = requests.get(base_url.rstrip('/') + path, timeout=5)
env = r.json()
assert isinstance(env, dict) and 'code' in env, f"unexpected envelope shape: {type(env).__name__}"

def is_valid_envelope(body: object) -> bool:
    return isinstance(body, dict) and "code" in body

try:
    resp = client.get(path)
except TDAMError as e:
    if e.code == -1 and e.message == "API response must be a JSON object":
        raise EnvelopeContractError("server returned non-object JSON; check endpoint/base_url") from e
    raise

When it happens

Trigger: post() or get() receives valid JSON that is not an object — an API gateway returning a JSON array of errors, a misconfigured mock returning "ok" or [], or a proxy returning a bare JSON scalar.

Common situations: Pointing the SDK at a stub/mock server or wrong endpoint that returns different JSON shapes; API gateway version mismatch changing the response envelope; CDN caching a non-envelope JSON document.

Related errors

• <resp.text or "HTTP {resp.status_code} returned a non-JSON r
• ${TAG} ${path} envelope error ${env.code}: ${env.message ??
• {field} must contain only non-empty strings
• {field} accepts at most {max_items} items, got {len(deduped)
• v3 MemoryClient requires non-empty {', '.join(missing)} at c

AI-assisted analysis of TencentCloud/TencentDB-Agent-Memory@3efcd317b8 (2026-09-01). Data as JSON: /api/errors/957a399c4fd4b722. Report an issue: GitHub.