오류 형식
모든 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 | 지원되지 않거나 유효하지 않은 체인 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 | 서버 오류 | 백오프를 적용하여 재시도합니다. 지속되면 지원팀에 문의합니다 |