錯誤格式
所有 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 | 伺服器錯誤 | 使用退避策略重試；若持續發生請聯繫支援 |