Chuyển đến nội dung chính

Định dạng Lỗi

Tất cả lỗi API AgentWallex tuân theo định dạng JSON nhất quán:
{
  "code": "invalid_request",
  "type": "invalid_request_error",
  "message": "human readable error description"
}
TrườngMô tả
codeMã lỗi máy đọc được (ví dụ: policy_violation, insufficient_funds)
typeDanh mục lỗi (xem bảng bên dưới)
messageMô tả con người đọc được về điều gì đã xảy ra sai

Các Loại Lỗi

LoạiMã HTTPMô tả
invalid_request_error400Nội dung yêu cầu hoặc tham số không hợp lệ
authentication_error401Thiếu hoặc khóa API / token không hợp lệ
authorization_error403Thông tin xác thực hợp lệ nhưng không đủ quyền
not_found_error404Tài nguyên được yêu cầu không tồn tại
rate_limit_error429Quá nhiều yêu cầu — thử lại sau thời gian chỉ định
internal_error500Lỗi phía server — liên hệ hỗ trợ nếu kéo dài

Mã Lỗi Phổ biến

LoạiMô tả
policy_violationinvalid_request_errorGiao dịch bị chặn bởi công cụ chính sách
insufficient_fundsinvalid_request_errorSố dư ví quá thấp cho giao dịch
agent_frozeninvalid_request_errorTác nhân bị đóng băng — mở đóng băng trước khi giao dịch
invalid_chaininvalid_request_errorChain ID không được hỗ trợ hoặc không hợp lệ
invalid_tokeninvalid_request_errorToken không được hỗ trợ trên chuỗi được chỉ định
invalid_addressinvalid_request_errorĐịa chỉ người nhận không đúng định dạng
session_expiredinvalid_request_errorPhiên x402 đã hết hạn hoặc vượt ngân sách
rate_limit_exceededrate_limit_errorĐã đạt giới hạn tốc độ API
approval_timeoutinvalid_request_errorPhê duyệt con người không được cấp trong thời gian chờ

Xử lý Lỗi SDK

TypeScript

SDK TypeScript cung cấp các lớp lỗi có kiểu cho các loại lỗi cụ thể:
import {
  AgentWallexError,
  PolicyViolationError,
} from "@agentwallex/sdk";

try {
  const tx = await aw.payments.send({
    agentId: "agent_abc123",
    to: "0xRecipientAddress",
    amount: "50.00",
    token: "USDC",
  });
} catch (error) {
  if (error instanceof PolicyViolationError) {
    console.log(`Policy violated: ${error.rule}`);
    console.log(`Details: ${error.message}`);
    // Handle: adjust amount, use different address, etc.
  } else if (error instanceof AgentWallexError) {
    console.log(`API error [${error.code}]: ${error.message}`);

    switch (error.code) {
      case "insufficient_funds":
        // Top up the wallet
        break;
      case "agent_frozen":
        // Unfreeze or use a different agent
        break;
      case "rate_limit_exceeded":
        // Wait and retry
        break;
      default:
        // Log and alert
        break;
    }
  } else {
    // Network error or unexpected exception
    console.error("Unexpected error:", error);
  }
}

Python

from agentwallex import AgentWallexError, PolicyViolationError

try:
    tx = await aw.payments.send(
        agent_id="agent_abc123",
        to="0xRecipientAddress",
        amount="50.00",
        token="USDC",
    )
except PolicyViolationError as e:
    print(f"Policy violated: {e.rule}")
    print(f"Details: {e.message}")
except AgentWallexError as e:
    print(f"API error [{e.code}]: {e.message}")
except Exception as e:
    print(f"Unexpected error: {e}")

Chiến lược Thử lại

Sử dụng backoff theo cấp số nhân cho việc thử lại. Chỉ thử lại với rate_limit_errorinternal_error. Không thử lại invalid_request_error hoặc authentication_error — những lỗi đó yêu cầu sửa yêu cầu.
async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries: number = 3
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (
        error instanceof AgentWallexError &&
        (error.type === "rate_limit_error" || error.type === "internal_error") &&
        attempt < maxRetries
      ) {
        const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
  throw new Error("Max retries exceeded");
}

// Usage
const tx = await withRetry(() =>
  aw.payments.send({
    agentId: "agent_abc123",
    to: "0xRecipientAddress",
    amount: "50.00",
    token: "USDC",
  })
);

Tham chiếu Mã trạng thái HTTP

Trạng tháiÝ nghĩaHành động
200Thành côngXử lý phản hồi
201Đã tạoTài nguyên được tạo thành công
400Yêu cầu saiSửa tham số yêu cầu
401Chưa xác thựcKiểm tra khóa API
403Bị cấmKiểm tra quyền / cấp gói
404Không tìm thấyXác minh ID tài nguyên tồn tại
429Bị giới hạn tốc độChờ và thử lại với backoff
500Lỗi ServerThử lại với backoff; liên hệ hỗ trợ nếu kéo dài