{"record":{"id":"06535cf563d4794d","repo":"TencentCloud/TencentDB-Agent-Memory","slug":"tag-path-envelope-error-env-code-env-m","errorCode":null,"errorMessage":"${TAG} ${path} envelope error ${env.code}: ${env.message ?? \"\"}","messagePattern":"(.+?) (.+?) envelope error (.+?): (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"MemoryProxy/src/meta/client.ts","lineNumber":559,"sourceCode":"    } catch (err) {\n      throw new Error(`${TAG} ${path} fetch failed: ${(err as Error).message}`);\n    }\n\n    if (!resp.ok) {\n      let detail = \"\";\n      try {\n        detail = await resp.text();\n      } catch { /* ignore */ }\n      console.log(\n        `[wb-debug] metadata-client req path=${path} status=${resp.status} url=${url} serviceId=${this.serviceId} userKey.len=${this.userKey?.length ?? 0} userKey.prefix=${(this.userKey ?? \"\").slice(0, 20)} serviceToken.len=${this.serviceToken?.length ?? 0} body.len=${detail.length} body.head=${detail.slice(0, 300)}`,\n      );\n      throw new Error(`${TAG} ${path} HTTP ${resp.status}${detail ? `: ${detail.slice(0, 200)}` : \"\"}`);\n    }\n\n    const env = (await resp.json()) as CoreEnvelope<T>;\n\n    if (env.code !== 0) {\n      throw new Error(`${TAG} ${path} envelope error ${env.code}: ${env.message ?? \"\"}`);\n    }\n\n    if (env.data === null || env.data === undefined) {\n      throw new Error(`${TAG} ${path} unexpected null data`);\n    }\n\n    return env.data as T;\n  }\n}\n\n// ── Singleton + test injection ──────────────────────────────────────────────\n\nlet _client: MetadataClient | null = null;\nlet _clientKey = \"\";\nlet _forced = false;\n\nfunction clientKey(cfg: Pick<CoreSkillConfig, \"endpoint\" | \"serviceToken\" | \"timeoutMs\">, serviceId: string, userKey: string): string {\n  return `${cfg.endpoint}::${cfg.serviceToken}::${serviceId}::${cfg.timeoutMs}::${userKey}`;","sourceCodeStart":541,"sourceCodeEnd":577,"githubUrl":"https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/3efcd317b84146d6a08518ac0f7ee7c8a8d200ec/MemoryProxy/src/meta/client.ts#L541-L577","documentation":"The metadata service returned HTTP 200 but its JSON envelope carried a non-zero business code (env.code !== 0), so fetch throws with the path, code, and server message. This is the library's signal for application-level errors that arrive inside a successful HTTP response.","triggerScenarios":"createTask/updateTask/appendParticipationLog receives a CoreEnvelope with code != 0 — e.g. business validation rejection, permission denied at the application layer, quota exceeded, or duplicate resource.","commonSituations":"Server-side validation rules rejecting payloads that pass client-side checks; tenant quotas exhausted; operations on resources in a state that disallows the mutation (e.g. updating a closed task).","solutions":["Read env.code and env.message from the error text and look up the code in the metadata service API docs","Fix the request payload per the server's message (usually the authoritative cause)","Check tenant/project quotas and permissions on the service side","Handle specific business codes in calling code (retryable vs permanent) instead of blanket retries"],"exampleFix":"// before\nawait client.updateTask(id, { status: \"closed\" }); // envelope error 1201: task already closed\n// after\nconst task = await client.getTask(id);\nif (task.status !== \"closed\") await client.updateTask(id, { status: \"closed\" });","handlingStrategy":"try-catch","validationCode":"// check resource state before mutating\ndef validateTaskUpdate(task, patch) {\n  if (task.status === \"closed\" && patch.status) throw new Error(\"cannot update closed task\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  await client.appendParticipationLog(entry);\n} catch (e) {\n  const m = /envelope error (\\d+):\\s*(.*)$/.exec(e.message);\n  if (m) {\n    const [code, msg] = [Number(m[1]), m[2]];\n    if (RETRYABLE_ENVELOPE_CODES.has(code)) await backoffRetry();\n    else console.error(`metadata rejected: code=${code} msg=${msg}`);\n  } else throw e;\n}","preventionTips":["Map known business codes to explicit handling in your app","Read the server message — it is the authoritative cause","Check quotas/permissions in the service console on repeated envelope errors","Pre-check resource state to avoid invalid-state mutations"],"tags":["api","envelope","business-error","metadata"],"backgroundTag":"api-error-envelope","analyzedSha":"3efcd317b84146d6a08518ac0f7ee7c8a8d200ec","analyzedAt":"2026-09-01T05:44:22.276Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}