Saltar al contenido principal

Formato de errores

Todos los errores de la API de AgentWallex siguen un formato JSON consistente:
{
  "code": "invalid_request",
  "type": "invalid_request_error",
  "message": "human readable error description"
}
CampoDescripción
codeCódigo de error legible por máquina (por ejemplo, policy_violation, insufficient_funds)
typeCategoría de error (consulte la tabla a continuación)
messageDescripción legible por humanos de lo que salió mal

Tipos de errores

TipoEstado HTTPDescripción
invalid_request_error400El cuerpo de la solicitud o los parámetros son inválidos
authentication_error401Clave API / token faltante o inválido
authorization_error403Credenciales válidas pero permisos insuficientes
not_found_error404El recurso solicitado no existe
rate_limit_error429Demasiadas solicitudes — reintente después del retraso indicado
internal_error500Error del lado del servidor — contacte a soporte si persiste

Códigos de error comunes

CódigoTipoDescripción
policy_violationinvalid_request_errorTransacción bloqueada por el motor de políticas
insufficient_fundsinvalid_request_errorSaldo de billetera insuficiente para la transacción
agent_frozeninvalid_request_errorEl agente está congelado — descongele antes de transaccionar
invalid_chaininvalid_request_errorChain ID no soportado o inválido
invalid_tokeninvalid_request_errorToken no soportado en la cadena especificada
invalid_addressinvalid_request_errorDirección del destinatario mal formada
session_expiredinvalid_request_errorLa sesión x402 ha expirado o excedido el presupuesto
rate_limit_exceededrate_limit_errorLímite de tasa de API alcanzado
approval_timeoutinvalid_request_errorLa aprobación humana no se otorgó dentro del tiempo límite

Manejo de errores en SDK

TypeScript

El SDK de TypeScript proporciona clases de error tipadas para tipos de error específicos:
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}")

Estrategia de reintentos

Use retroceso exponencial para los reintentos. Solo reintente en rate_limit_error e internal_error. No reintente invalid_request_error o authentication_error — estos requieren corregir la solicitud.
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",
  })
);

Referencia de códigos de estado HTTP

EstadoSignificadoAcción
200ÉxitoProcese la respuesta
201CreadoEl recurso fue creado exitosamente
400Solicitud incorrectaCorrija los parámetros de la solicitud
401No autorizadoVerifique su clave API
403ProhibidoVerifique los permisos / nivel de plan
404No encontradoVerifique que el ID del recurso existe
429Límite de tasaEspere y reintente con retroceso
500Error del servidorReintente con retroceso; contacte a soporte si persiste