Codigos de Error

Referencia completa de errores de pan API

Estructura de Error

{
  "error": "ERROR_CODE",
  "message": "Descripción legible del error",
  "details": {
    "campo": "información adicional"
  }
}

Errores de Autenticación

UNAUTHORIZED

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

Codigo HTTP: 401

Causas:

• Header Authorization faltante
• API key mal formateada
• API key revocada o invalida

Solución:

// Verificar formato correcto
headers: {
  'Authorization': `Bearer ${apiKey}` // Nota el espacio
}

FORBIDDEN

{
  "error": "FORBIDDEN",
  "message": "Access denied"
}

Codigo HTTP: 403

Causas:

• Créditos insuficientes
• Plan no permite está operación
• Acceso a recurso de otro developer

Errores de Validación

INVALID_REQUEST

{
  "error": "INVALID_REQUEST",
  "message": "Invalid request body",
  "details": {
    "field": "amount",
    "issue": "Must be a positive number"
  }
}

Codigo HTTP: 400

Causas:

• Campo requerido faltante
• Tipo de dato incorrecto
• Valor fuera de rango

INVALID_WALLET_ID

{
  "error": "INVALID_WALLET_ID",
  "message": "Wallet ID format is invalid",
  "details": {
    "provided": "wallet123",
    "expected": "pan_wallet_*"
  }
}

Codigo HTTP: 400

INVALID_CHAIN

{
  "error": "INVALID_CHAIN",
  "message": "Chain not supported",
  "details": {
    "provided": "polygon",
    "supported": ["ethereum", "arbitrum", "base"]
  }
}

Codigo HTTP: 400

Errores de Recursos

WALLET_NOT_FOUND

{
  "error": "WALLET_NOT_FOUND",
  "message": "Wallet not found for user",
  "details": {
    "userId": "usuario_123"
  }
}

Codigo HTTP: 404

Solución: Crear wallet primero o verificar userId

INTENT_NOT_FOUND

{
  "error": "INTENT_NOT_FOUND",
  "message": "Intent not found",
  "details": {
    "intentId": "intent_xyz789"
  }
}

Codigo HTTP: 404

WALLET_ALREADY_EXISTS

{
  "error": "WALLET_ALREADY_EXISTS",
  "message": "Wallet already exists for this user",
  "details": {
    "userId": "usuario_123",
    "existingWalletId": "pan_wallet_abc123"
  }
}

Codigo HTTP: 409

Solución: Usar GET para obtener wallet existente

Errores de Limites

WALLET_LIMIT_EXCEEDED

{
  "error": "WALLET_LIMIT_EXCEEDED",
  "message": "Maximum wallet limit reached for your plan",
  "details": {
    "limit": 100,
    "current": 100,
    "plan": "free"
  }
}

Codigo HTTP: 403

Solución: Actualizar plan o eliminar wallets no usadas

RATE_LIMITED

{
  "error": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "limit": 100,
    "window": "1 minute",
    "retryAfter": 45
  }
}

Codigo HTTP: 429

Headers:

Retry-After: 45
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642248045

Solución: Implementar backoff exponencial

INSUFFICIENT_CREDITS

{
  "error": "INSUFFICIENT_CREDITS",
  "message": "Not enough credits for this operation",
  "details": {
    "required": 5,
    "available": 2
  }
}

Codigo HTTP: 402

Solución: Comprar más créditos o actualizar plan

Errores de Ejecución

INSUFFICIENT_FUNDS

{
  "error": "INSUFFICIENT_FUNDS",
  "message": "Wallet does not have sufficient funds",
  "details": {
    "asset": "USDC",
    "required": "1000",
    "available": "750",
    "shortfall": "250"
  }
}

Codigo HTTP: 400

Solución: Depositar más fondos antes de ejecutar

BRIDGE_FAILED

{
  "error": "BRIDGE_FAILED",
  "message": "Bridge operation failed",
  "details": {
    "from": "arbitrum",
    "to": "base",
    "reason": "Fill timeout exceeded"
  }
}

Codigo HTTP: 500

Nota: Los fondos permanecen en la chain origen

DEPOSIT_FAILED

{
  "error": "DEPOSIT_FAILED",
  "message": "Deposit to protocol failed",
  "details": {
    "protocol": "aave",
    "chain": "base",
    "reason": "Transaction reverted"
  }
}

Codigo HTTP: 500

EXECUTION_TIMEOUT

{
  "error": "EXECUTION_TIMEOUT",
  "message": "Execution exceeded maximum time",
  "details": {
    "elapsed": "600s",
    "maxAllowed": "600s"
  }
}

Codigo HTTP: 504

Errores de Servidor

INTERNAL_ERROR

{
  "error": "INTERNAL_ERROR",
  "message": "An unexpected error occurred"
}

Codigo HTTP: 500

Solución: Reintentar con backoff, contactar soporte si persiste

SERVICE_UNAVAILABLE

{
  "error": "SERVICE_UNAVAILABLE",
  "message": "Service temporarily unavailable"
}

Codigo HTTP: 503

Solución: Reintentar después del Retry-After header

Manejo de Errores

async function requestConManejo(fn) {
  try {
    return await fn();
  } catch (error) {
    switch (error.code) {
      case 'RATE_LIMITED':
        const wait = error.details?.retryAfter || 60;
        await sleep(wait * 1000);
        return requestConManejo(fn);

      case 'INSUFFICIENT_FUNDS':
        throw new UserError(`Necesitas ${error.details.shortfall} mas`);

      case 'WALLET_NOT_FOUND':
        // Crear wallet automaticamente
        return await crearWallet(error.details.userId);

      case 'INTERNAL_ERROR':
      case 'SERVICE_UNAVAILABLE':
        // Reintentar con backoff
        await sleep(5000);
        return requestConManejo(fn);

      default:
        throw error;
    }
  }
}