错误格式
所有 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_error | 400 | 请求体或参数无效 |
authentication_error | 401 | API 密钥/令牌缺失或无效 |
authorization_error | 403 | 凭证有效但权限不足 |
not_found_error | 404 | 请求的资源不存在 |
rate_limit_error | 429 | 请求过多 — 在指定延迟后重试 |
internal_error | 500 | 服务器端错误 — 如果持续出现请联系支持 |
常见错误代码
| 代码 | 类型 | 说明 |
|---|---|---|
policy_violation | invalid_request_error | 交易被策略引擎阻止 |
insufficient_funds | invalid_request_error | 钱包余额不足以完成交易 |
agent_frozen | invalid_request_error | 代理已冻结 — 解冻后才能交易 |
invalid_chain | invalid_request_error | 不支持或无效的 Chain ID |
invalid_token | invalid_request_error | 指定链上不支持该代币 |
invalid_address | invalid_request_error | 收款方地址格式错误 |
session_expired | invalid_request_error | x402 会话已过期或超出预算 |
rate_limit_exceeded | rate_limit_error | API 速率限制已达到 |
approval_timeout | invalid_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 | 服务器错误 | 使用退避重试；如果持续出现请联系支持 |