Error Handling

Version Requirement

AI-friendly error handling architecture requires @lovrabet/sdk v1.2.5 or higher.

Lovrabet SDK adopts an AI-friendly error handling architecture, specifically designed for Vibe Coding (AI-assisted programming) scenarios. When you use the SDK in AI programming tools like Cursor, Claude Code, Copilot, etc., error messages can be directly understood by AI and automatically provide fix suggestions.

Design Philosophy

Why AI-Friendly Errors?

Traditional error handling only focuses on human developers:

// Traditional error - AI struggles to understand context
Error: "project_id column cannot be empty"

In Vibe Coding scenarios, AI needs more context to help you fix problems:

• What type of error is this? Parameter error? Permission issue?
• Which specific field has the problem?
• How should it be fixed? What are the suggestions?
• How to get correct field information?

Lovrabet SDK's AI-friendly architecture is designed to solve these problems.

Architecture Goals

1. Errors understandable by AI - Structured error information, including error type, cause, status code
2. Provide fix suggestions - Give specific fix directions for different error types
3. Guide AI to use tools - When more information is needed, guide AI to call MCP tools to obtain it
4. Support automatic fixes - AI can automatically modify code based on suggestions

---

LovrabetError Type

All SDK errors are thrown using the unified LovrabetError type:

import { LovrabetError } from "@lovrabet/sdk";

try {
  await client.models.users.create({ name: "Zhang San" });
} catch (error) {
  if (error instanceof LovrabetError) {
    console.log(error.message);     // Error message
    console.log(error.code);        // Error code
    console.log(error.status);      // HTTP status code
    console.log(error.description); // AI-friendly detailed description ⭐
    console.log(error.response);    // Server raw response
  }
}

Error Properties Explained

Property	Type	Purpose	How AI Uses It
message	string	Short error message	Quickly understand the problem
code	string	Error code	Determine error category
status	number	HTTP status code	Determine if it's a client or server issue
description	string	AI-friendly detailed description	Understand error cause, get fix suggestions
response	object	Raw response	Get more details when needed

---

AI-Friendly description Field

description is the core field designed specifically for AI by the SDK (v1.2.5+), containing:

1. Error cause - What error did the server return
2. Error classification - What type of error is this
3. Status code - What is the HTTP status code
4. Fix suggestions - Targeted fix directions

Structure of description

Server returned error: {error message}. Error type: {type}. Status code: {status}. Suggestion: {specific suggestion}

This structured natural language format allows AI to:

• Parse key information (field name, error type)
• Understand problem severity
• Take action according to suggestions

---

Vibe Coding Practical Scenarios

The following demonstrates how AI uses description to automatically fix errors.

Scenario One: Field Name Spelling Error

You write code in Cursor:

await client.models.users.create({
  naem: "Zhang San",  // Spelling error
  phone: "13800138000"
});

After running, SDK throws error:

LovrabetError {
  message: "Column naem does not exist",
  code: "SERVER_ERROR",
  status: 400,
  description: "Server returned error: Column naem does not exist. Error type: Parameter error. Status code: 400. Suggestion: Field \"naem\" does not exist, please check if the field name is spelled correctly; Use MCP tool to get the correct field list for the dataset"
}

AI's Understanding Process:

1. Parse description, find it's a "parameter error"
2. Identify problem field is naem
3. See suggestion "check if field name is spelled correctly"
4. Infer naem might be a spelling error for name
5. Automatically fix code

// After AI auto-fix
await client.models.users.create({
  name: "Zhang San",  // Fixed
  phone: "13800138000"
});

Scenario Two: Missing Required Field

await client.models.orders.create({
  name: "Order 1",
  amount: 100
});

SDK error message:

LovrabetError {
  message: "Column project_id cannot be empty",
  code: "SERVER_ERROR",
  status: 400,
  description: "Server returned error: Column project_id cannot be empty. Error type: Parameter error. Status code: 400. Suggestion: Field \"project_id\" is required, please ensure this field is passed"
}

AI's Handling Approach:

1. Identify project_id is required
2. Check current code, confirm this field is indeed missing
3. May query dataset structure through MCP tool to understand project_id type
4. Prompt user to add this field, or automatically add based on context

Scenario Three: Permission/Login Issue

await client.models.users.filter();

SDK error message:

LovrabetError {
  message: "Insufficient permissions",
  code: "SERVER_ERROR",
  status: 401,
  description: "Server returned error: Insufficient permissions. Error type: 202. Status code: 401. Suggestion: Check if user login status has expired, need to re-login; Check if appCode has permission to access this dataset; Ensure using HTTPS protocol; Check for cross-origin issues (CORS)"
}

AI's Troubleshooting Direction:

1. See 401 status code, identify as authentication issue
2. According to suggestions, check in order:
   • Whether login status expired
   • appCode permission configuration
   • HTTPS protocol
   • CORS configuration
3. Provide user with specific troubleshooting steps

---

Collaboration with MCP Tools

description will guide AI to use MCP tools to get more information:

Suggestion: Field "xxx" does not exist, please check if the field name is spelled correctly; Use MCP tool to get the correct field list for the dataset

When AI sees this suggestion, it will call MCP tool:

// AI calls MCP tool
const datasetInfo = await mcp.tools.get_dataset_detail({
  datasetCode: "users"
});

// Get correct field list
const fields = datasetInfo.fields;
// ["id", "name", "phone", "email", "created_at", ...]

Then AI can:

• Find correct field names
• Understand which fields are required
• Know field types and format requirements

This SDK + MCP collaborative architecture allows AI to fully understand and solve problems.

---

Error Code Reference

Client Error Codes

Error Code	Description	description Content
MODEL_NOT_FOUND	Model does not exist	List all available models (datasetCode, alias, name)
MODEL_INDEX_OUT_OF_RANGE	Model index out of range	Provide valid index range
CONFIG_NOT_FOUND	Configuration does not exist	List registered configuration names
APP_CODE_REQUIRED	Missing appCode	Provide configuration example
TIMEOUT	Request timeout	Current timeout time, optimization suggestions
OPENAPI_AUTH_PARAMS_MISSING	OpenAPI authentication parameters missing	List missing parameters

Server Error Codes

Error Type	HTTP Status Code	description Content
Parameter Error	400	Field fix suggestions (required, spelling, format)
Insufficient Permissions	401	Login status, appCode, HTTPS, CORS check suggestions
Other Errors	Various	Basic information (error type, message, status code)

---

Best Practices

Let AI See Error Information

In Vibe Coding, ensure error information can be captured by AI tools:

try {
  await client.models.users.create(formData);
} catch (error) {
  if (error instanceof LovrabetError) {
    // Output description, AI tools will read console
    console.error("SDK Error:", error.description);

    // Or throw directly, let AI see full stack
    throw error;
  }
}

Global Error Handling

Configure global error handling to uniformly output AI-friendly information:

const client = createClient({
  appCode: "your-app-code",
  options: {
    onError: (error: LovrabetError) => {
      // Output AI-friendly description
      console.error("[Lovrabet SDK Error]", error.description);

      // 401 auto redirect to login
      if (error.status === 401) {
        window.location.href = "/login";
      }
    },
  },
  models: [
    { tableName: "users", datasetCode: "xxx", alias: "users" },
  ],
});

Development Environment Enhanced Output

Output more information in development environment:

function handleError(error: LovrabetError) {
  if (process.env.NODE_ENV === "development") {
    console.group("LovrabetError Debug Info");
    console.log("Message:", error.message);
    console.log("Code:", error.code);
    console.log("Status:", error.status);
    console.log("Description:", error.description);
    console.log("Response:", JSON.stringify(error.response, null, 2));
    console.groupEnd();
  }
}

---

Error Type Judgment

By HTTP Status Code

if (error instanceof LovrabetError) {
  switch (error.status) {
    case 400:
      // Parameter error - AI can auto-fix based on description
      break;
    case 401:
      // Authentication failed - need to re-login
      break;
    case 403:
      // Insufficient permissions - check appCode configuration
      break;
    case 500:
      // Server error - need to contact operations
      break;
  }
}

By Error Code

if (error instanceof LovrabetError) {
  switch (error.code) {
    case "MODEL_NOT_FOUND":
      // View description to get available model list
      console.log(error.description);
      break;
    case "SERVER_ERROR":
      // View description to get specific cause and suggestions
      console.log(error.description);
      break;
  }
}

---

Summary

Lovrabet SDK's AI-friendly error handling architecture:

Feature	Description
Unified Error Type	All errors are LovrabetError, easy for unified handling
AI-Understandable description	Contains error cause, type, suggestions, AI can directly parse
Targeted Fix Suggestions	Different error types provide different fix directions
MCP Tool Collaboration	Guide AI to use MCP to get more information
Support Automatic Fixes	AI can automatically modify code based on information

In the Vibe Coding era, good error messages should not only be understandable by humans, but also be understood by AI to help solve problems.

For more advanced error handling patterns (retry mechanisms, circuit breakers, etc.), please refer to Advanced Features.