{"record":{"id":"957a399c4fd4b722","repo":"TencentCloud/TencentDB-Agent-Memory","slug":"1","errorCode":"-1","errorMessage":"API response must be a JSON object","messagePattern":"API response must be a JSON object","errorType":"error_code","errorClass":"TDAMError","httpStatus":null,"severity":"error","filePath":"sdk/memory-core/python/tencentdb_agent_memory/_v3_http.py","lineNumber":51,"sourceCode":"        raise ParamError(\"service_id must be provided\")\n    if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or timeout <= 0:\n        raise ParamError(\"timeout must be a positive number\")\n\n\ndef _decode_response(resp: httpx.Response) -> dict:\n    header_request_id = (\n        resp.headers.get(\"x-qcloud-transaction-id\")\n        or resp.headers.get(\"x-trace-id\")\n        or \"\"\n    )\n    try:\n        envelope = resp.json()\n    except ValueError as exc:\n        message = resp.text or f\"HTTP {resp.status_code} returned a non-JSON response\"\n        raise TDAMError(resp.status_code if resp.is_error else -1, message, header_request_id) from exc\n\n    if not isinstance(envelope, dict):\n        raise TDAMError(-1, \"API response must be a JSON object\", header_request_id)\n\n    code = envelope.get(\"code\")\n    if resp.is_error or code != 0:\n        effective_code = code if isinstance(code, int) and code != 0 else resp.status_code\n        payload = envelope.get(\"data\")\n        details = payload if isinstance(payload, dict) else None\n        raise TDAMError(\n            code=effective_code,\n            message=str(envelope.get(\"message\") or f\"HTTP {resp.status_code}\"),\n            request_id=str(envelope.get(\"request_id\") or header_request_id),\n            details=details,\n        )\n\n    result = envelope.get(\"data\") or {}\n    if not isinstance(result, dict):\n        raise TDAMError(-1, \"API response data must be a JSON object\", header_request_id)\n    trace_id = resp.headers.get(\"x-trace-id\")\n    if trace_id:","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/3efcd317b84146d6a08518ac0f7ee7c8a8d200ec/sdk/memory-core/python/tencentdb_agent_memory/_v3_http.py#L33-L69","documentation":"_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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Confirm the endpoint returns the documented envelope object {\"code\":..., \"data\":...}","Check base_url/path configuration for stub, mock, or outdated gateway URLs","Capture the raw response (curl the same URL) to see the actual JSON type being returned","Upgrade/downgrade the SDK to match the server's envelope contract version"],"exampleFix":"# before\nclient = TDAMClient(base_url=\"http://localhost:9000/mock\")  # mock returns []\n# after\nclient = TDAMClient(base_url=\"https://api.example.com/v3\")  # returns {\"code\":0,\"data\":{...}}","handlingStrategy":"type-guard","validationCode":"# preflight: confirm the endpoint returns an object envelope\nimport requests, json\nr = requests.get(base_url.rstrip('/') + path, timeout=5)\nenv = r.json()\nassert isinstance(env, dict) and 'code' in env, f\"unexpected envelope shape: {type(env).__name__}\"","typeGuard":"def is_valid_envelope(body: object) -> bool:\n    return isinstance(body, dict) and \"code\" in body","tryCatchPattern":"try:\n    resp = client.get(path)\nexcept TDAMError as e:\n    if e.code == -1 and e.message == \"API response must be a JSON object\":\n        raise EnvelopeContractError(\"server returned non-object JSON; check endpoint/base_url\") from e\n    raise","preventionTips":["Pin the SDK and server to compatible envelope contract versions","Test against the real endpoint, not stubs returning bare arrays/scalars","Validate the envelope shape in integration tests","Capture raw responses when diagnosing contract mismatches"],"tags":["python","json","envelope","contract"],"backgroundTag":"api-response-envelope-mismatch","analyzedSha":"3efcd317b84146d6a08518ac0f7ee7c8a8d200ec","analyzedAt":"2026-09-01T05:44:22.276Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}