跳转到主要内容

​
错误格式

所有 AgentWallex API 错误遵循一致的 JSON 格式： 
{
  "code": "invalid_request",
  "type": "invalid_request_error",
  "message": "human readable error description"
}
字段说明
code机器可读的错误代码（例如 policy_violation、insufficient_funds）
type错误类别（见下表）
message人类可读的错误描述

​
错误类型

类型HTTP 状态码说明
invalid_request_error400请求体或参数无效
authentication_error401API 密钥/令牌缺失或无效
authorization_error403凭证有效但权限不足
not_found_error404请求的资源不存在
rate_limit_error429请求过多 — 在指定延迟后重试
internal_error500服务器端错误 — 如果持续出现请联系支持

​
常见错误代码

代码类型说明
policy_violationinvalid_request_error交易被策略引擎阻止
insufficient_fundsinvalid_request_error钱包余额不足以完成交易
agent_frozeninvalid_request_error代理已冻结 — 解冻后才能交易
invalid_chaininvalid_request_error不支持或无效的 Chain ID
invalid_tokeninvalid_request_error指定链上不支持该代币
invalid_addressinvalid_request_error收款方地址格式错误
session_expiredinvalid_request_errorx402 会话已过期或超出预算
rate_limit_exceededrate_limit_errorAPI 速率限制已达到
approval_timeoutinvalid_request_error人工审批未在超时时间内完成

​
SDK 错误处理

​
TypeScript

TypeScript SDK 为特定错误类型提供了类型化的错误类： 
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}")

​
重试策略

使用指数退避进行重试。仅对 rate_limit_error 和 internal_error 进行重试。不要重试 invalid_request_error 或 authentication_error — 这些需要修复请求本身。
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",
  })
);

​
HTTP 状态码参考

状态码含义操作
200成功处理响应
201已创建资源创建成功
400请求错误修复请求参数
401未授权检查 API 密钥
403禁止访问检查权限/计划等级
404未找到验证资源 ID 是否存在
429速率限制等待并使用退避重试
500服务器错误使用退避重试；如果持续出现请联系支持