# Memory Core API Response Envelope Structure: A Complete Technical Guide

> Understand the Memory Core API response envelope structure, detailing code, message, request_id, and data fields for consistent error handling and parsing.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: api-reference
- Published: 2026-09-02

---

**Memory Core API calls return a standardized JSON envelope with four fields—`code`, `message`, `request_id`, and `data`—enabling uniform error handling and response parsing across all endpoints.**

The **TencentDB Agent Memory** system's Memory Core component wraps every HTTP API response in a predictable structure. This envelope design, implemented in the gateway layer, ensures clients can reliably check operation status and extract business data without parsing variations between endpoints. According to the TencentCloud source code, both V2 and V3 API versions share this envelope format, with V3 adding stricter isolation requirements.

---

## Response Envelope Fields

Every **Memory Core API response envelope** contains four standardized fields. These are defined in [`MemoryCore/src/gateway/v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-router.ts) and enforced across all gateway routes.

| Field | Type | Description |
|-------|------|-------------|
| **code** | `number` | `0` indicates success; non-zero values signal errors (`400`, `401`, `500`, or 5-digit skill-module codes) |
| **message** | `string` | `"ok"` for success; human-readable error description otherwise |
| **request_id** | `string` | Unique identifier from inbound `x-request-id` / `x-qcloud-transaction-id` header, or auto-generated as `req-<uuid>` |
| **data** | `any` | Business-level payload on success; omitted or contains `errorEnvelope` diagnostics on failure |

The envelope guarantees that **client code can always check `code === 0`** before accessing `data`, regardless of which Memory Core endpoint was called.

---

## Envelope Implementation in Source Code

The envelope constructors reside in [`MemoryCore/src/gateway/v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-router.ts) at lines 32-38. The **TencentCloud/TencentDB-Agent-Memory** repository uses two helper functions to ensure consistency:

### successEnvelope Helper

```typescript
export function successEnvelope<T>(data: T, requestId: string): ApiResponseEnvelope<T> {
  return { code: 0, message: "ok", request_id: requestId, data };
}

```

This helper is invoked for all successful responses, wrapping the business result with the standard fields.

### errorEnvelope Helper

```typescript
export function errorEnvelope(
  code: number,
  message: string,
  requestId: string,
  extra?: Record<string, unknown>,
): ApiResponseEnvelope {
  return { code, message, request_id: requestId, ...(extra ? { data: extra } : {}) };
}

```

The `extra` parameter allows optional diagnostic data to be attached under the `data` field for debugging purposes.

---

## Real Response Examples

### Successful Conversation Add Response

```json
{
  "code": 0,
  "message": "ok",
  "request_id": "req-1a2b3c4d5e6f7g8h",
  "data": {
    "accepted_ids": ["msg-abc123"],
    "accepted_versions": ["v1"],
    "total_count": 1
  }
}

```

This response from `POST /v3/conversation/add` demonstrates the **Memory Core API response envelope** with a populated `data` object containing operation-specific results.

### Error Response for Missing Isolation Fields

```json
{
  "code": 422,
  "message": "/v3 requires strict isolation: missing team_id, agent_id, user_id.",
  "request_id": "req-9z8y7x6w5v4u3t2s"
}

```

V3 endpoints enforce stricter isolation and return `422` when required fields are absent. As documented in [`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) (lines 21-28), the `data` field is omitted here since no business payload exists.

---

## Using Envelope Helpers in Custom Code

The envelope utilities can be imported and reused when extending Memory Core's gateway:

```typescript
import { successEnvelope, errorEnvelope } from "./gateway/v2-router.js";

function handleCustomEndpoint(payload: RequestBody, reqId: string): ApiResponseEnvelope {
  if (!payload.requiredField) {
    return errorEnvelope(400, "Missing required field", reqId);
  }
  
  const result = executeBusinessLogic(payload);
  return successEnvelope(result, reqId);
}

```

This pattern ensures all custom endpoints remain compatible with the **Memory Core API response envelope** contract.

---

## V2 vs. V3 Envelope Behavior

While both versions use identical envelope structures, **V3 enforces additional validation**:

- **Isolation requirements**: V3 endpoints require `team_id`, `agent_id`, and `user_id` fields
- **Error specificity**: Missing isolation fields trigger `422` with descriptive messaging
- **Uniform parsing**: Client code needs no version-specific handling—the same `code`/`data` checks work everywhere

---

## Summary

- **Four fixed fields** compose every response: `code`, `message`, `request_id`, `data`
- **`code: 0`** always indicates success; non-zero values require error handling
- **Implementation location**: [`MemoryCore/src/gateway/v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-router.ts) defines `successEnvelope` and `errorEnvelope`
- **Version compatibility**: V2 and V3 share envelope structure; V3 adds isolation validation only
- **Request ID propagation**: Headers are preserved when present, or UUIDs are generated automatically

---

## Frequently Asked Questions

### What happens to the data field when a Memory Core API call fails?

The `data` field is **omitted** on most errors. However, if the `errorEnvelope` helper receives an `extra` parameter containing diagnostic information, that data is attached under `data` for debugging purposes. Production client code should check `code !== 0` and read `message` rather than expecting `data` to exist.

### How is the request_id generated if no request header is provided?

When inbound requests lack `x-request-id` or `x-qcloud-transaction-id` headers, the gateway **generates a local identifier** using the pattern `req-<uuid>`. This ensures every response remains traceable for logging and debugging, as implemented in the envelope construction logic.

### Can V2 and V3 endpoint responses be parsed with identical code?

**Yes.** Both versions return the same envelope structure with `code`, `message`, `request_id`, and `data` fields. The only behavioral difference is that V3 may return `422` errors for isolation violations. Client parsers need only check `code === 0` to determine success, then extract `data` accordingly.