TencentDB Agent Memory Skill Error Codes: Complete 5-Digit Reference Guide

The Skill module in TencentDB Agent Memory uses 15 specific 5-digit error codes, defined as constants in SkillErrorCode within sdk/memory-core/typescript/src/v3/skill-types.ts, ranging from 40001 (bad request) to 50303 (COS configuration missing).

The TencentDB Agent Memory SDK implements a structured error reporting system for its Skill module through numeric codes returned in API response envelopes. These 5-digit error codes provide precise diagnostics for all /v3/skill/* endpoints, enabling developers to identify and handle failure conditions programmatically. This guide lists every code, its meaning, and practical implementation patterns drawn directly from the source repository.

---

Where 5-Digit Skill Error Codes Are Defined

The canonical source of truth resides in sdk/memory-core/typescript/src/v3/skill-types.ts. Here, the SkillErrorCode constant object and SkillErrorCodeValue type establish the complete enumeration:

Constant	Description	Numeric Code
BAD_REQUEST	Invalid request parameters	40001
NOT_OWNER	Caller is not the owner of the resource	40301
TEAM_MISMATCH	Team ID does not match the requested resource	40302
NOT_FOUND	Requested skill or resource does not exist	40401
VERSION_STALE	Update conflict – stale version supplied	40901
VERSION_EXPIRED	Version has expired or is no longer valid	41002
RESOURCE_TOO_LARGE	Uploaded resource exceeds size limits	41301
QUOTA_EXCEEDED	Account or team quota has been exceeded	42901
NAME_DUPLICATE	Attempted to create a skill with a duplicate name	42201
PATCH_NOT_UNIQUE	Patch operation would result in non-unique fields	42202
FRONTMATTER_INVALID	Skill's front-matter (metadata) is malformed	42203
QUEUE_UNAVAILABLE	Internal queue service is unavailable	50301
STORAGE_NOT_FOUND	Underlying storage service could not locate the resource	50301
LLM_UNAVAILABLE	Large-language-model service is down or unreachable	50302
COS_REQUIRED	COS (Cloud Object Storage) configuration is missing	50303

Note: The source lists 4291 for QUOTA_EXCEEDED, which appears to be a typographical omission of the trailing zero; the intended code follows the 5-digit S-digit scheme as 42901.

---

Client-Side Error Codes (40000–42999)

Codes in the 4xx range indicate request or client-side issues. The Skill module uses custom suffixes (-001, -002, etc.) to distinguish specific failure modes within standard HTTP status families.

Request Validation (40001–40401)

• 40001 (BAD_REQUEST): Malformed parameters or missing required fields in the request payload.
• 40301 (NOT_OWNER): Authentication succeeded but the principal lacks ownership of the target skill.
• 40302 (TEAM_MISMATCH): The provided teamId does not match the resource's registered team, enforcing tenant isolation.
• 40401 (NOT_FOUND): The skillId or dependent resource does not exist in the current scope.

Concurrency and State Conflicts (40901–41002)

• 40901 (VERSION_STALE): Optimistic locking failure—the supplied version token does not match the server's current version. Retry with fresh state.
• 41002 (VERSION_EXPIRED): The version identifier has passed its validity window and cannot be used for updates.

Payload and Quota Limits (41301–42901)

• 41301 (RESOURCE_TOO_LARGE): Binary or metadata upload exceeds configured size thresholds.
• 42201 (NAME_DUPLICATE): Violates uniqueness constraint on skill names within the team scope.
• 42202 (PATCH_NOT_UNIQUE): A JSON Patch operation would create duplicate values in a field requiring uniqueness.
• 42203 (FRONTMATTER_INVALID): YAML/JSON front-matter parsing failed—check metadata schema compliance.
• 42901 (QUOTA_EXCEEDED): Rate limit or per-account skill creation quota depleted.

---

Server-Side Error Codes (50301–50303)

Codes in the 5xx range signal infrastructure or dependency failures. The Skill module reserves the 503 space for downstream service unavailability.

• 50301 (QUEUE_UNAVAILABLE / STORAGE_NOT_FOUND): Shared code indicating either the async job queue or the primary storage layer returned a missing-resource or unavailability signal. Disambiguate via message field.
• 50302 (LLM_UNAVAILABLE): The configured large language model endpoint (e.g., Tencent Hunyuan) is unreachable or returning errors.
• 50303 (COS_REQUIRED): The operation requires Cloud Object Storage configuration that is absent from the team or project settings.

---

Implementing Error Handling in TypeScript

The SDK exports SkillErrorCode and SkillErrorCodeValue for type-safe error branches. Use exhaustive switch statements or mapping tables to translate codes into user-facing messages.

Basic Handler Pattern

import { SkillErrorCode, type SkillErrorCodeValue } from "@tencent/memory-core/v3";

async function createSkill() {
  try {
    await skillClient.createSkill({ /* request payload */ });
  } catch (e) {
    const code = (e as any).code as SkillErrorCodeValue;
    
    switch (code) {
      case SkillErrorCode.BAD_REQUEST:
        console.error("Invalid parameters supplied.");
        break;
      case SkillErrorCode.NOT_FOUND:
        console.error("Skill does not exist.");
        break;
      case SkillErrorCode.QUOTA_EXCEEDED:
        console.error("Quota limit reached—contact support to increase limits.");
        break;
      case SkillErrorCode.VERSION_STALE:
        console.error("Conflict detected—refresh and retry the operation.");
        break;
      default:
        console.error(`Unhandled Skill error: ${code}`);
    }
  }
}

Inspecting Response Envelopes Directly

// Examining raw response for programmatic flow control
const response = await skillClient.getSkill({ skillId: "my-skill" });

if (response.code !== undefined && response.code !== 0) {
  // Non-zero code indicates error per S-digit scheme
  console.error(`Error ${response.code}: ${response.message}`);
  
  if (response.code === SkillErrorCode.COS_REQUIRED) {
    // Trigger COS onboarding workflow
    await promptForCosConfiguration();
  }
}

---

Key Source Files for Error Code Implementation

File	Responsibility
sdk/memory-core/typescript/src/v3/skill-types.ts	Exports SkillErrorCode constant and SkillErrorCodeValue type [source]
sdk/memory-core/typescript/src/v3/skill-client.ts	HTTP client translating /v3/skill/* responses into typed errors [source]
MemoryCore/src/core/skill/skill-store.ts	Server-side enforcement and emission of these codes [source]

---

Summary

• 15 distinct 5-digit error codes cover client validation, ownership, concurrency, quotas, and infrastructure failures in the Skill module.
• Source location: sdk/memory-core/typescript/src/v3/skill-types.ts defines SkillErrorCode and SkillErrorCodeValue.
• Pattern: HTTP status prefix + custom suffix (e.g., 40001 extends 400 Bad Request).
• Type safety: Import SkillErrorCode for compile-time checking instead of raw numeric literals.
• 50301 collision: QUEUE_UNAVAILABLE and STORAGE_NOT_FOUND share this code—inspect the message field to differentiate.

---

Frequently Asked Questions

What does the "S-digit" naming convention mean in TencentDB Agent Memory?

S-digit refers to the 5-digit numeric structure used throughout the SDK's error reporting: a 3-digit HTTP status family code followed by a 2-digit subcode. This scheme appears in Skill, Memory, and other module-specific error constants, providing granular error classification while maintaining HTTP semantics.

How do I handle version conflicts when updating a skill?

Catch 40901 (VERSION_STALE) and re-fetch before retrying. The Skill module uses optimistic concurrency control. When your version token mismatches the server state, the update is rejected with this code. Retrieve the current skill state via getSkill(), merge your changes, and resubmit with the fresh version identifier.

Why do QUEUE_UNAVAILABLE and STORAGE_NOT_FOUND share error code 50301?

Both map to infrastructure unavailability but originate from different subsystems. The server-side implementation in MemoryCore/src/core/skill/skill-store.ts uses 50301 for multiple transient failure modes. Your error handler should check the message string for "queue" versus "storage" to determine appropriate retry or escalation logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}